Feat: patient attributes v1 (local-first)

backend/api/conversation_routes.py

@@ -20,7 +20,11 @@ class StartConversationRequest(BaseModel):
     model: Optional[str] = Field(default=None, description="Override LLM model to use")
     patient_prompt_addition: Optional[str] = Field(
         default=None,
-        description="Extra instructions appended to the patient system prompt for this run",
+        description="(Deprecated) Extra instructions appended to the patient system prompt for this run",
+    )
+    patient_attributes: Optional[List[str]] = Field(
+        default=None,
+        description="Plain-language patient attributes (bullet lines) compiled into the patient system prompt",
     )
     surveyor_attributes: Optional[List[str]] = Field(
         default=None,
@@ -51,7 +55,7 @@ async def start_conversation(request: StartConversationRequest) -> Dict[str, str
             patient_persona_id=request.patient_persona_id,
             host=request.host,
             model=request.model,
-            patient_prompt_addition=request.patient_prompt_addition,
+            patient_attributes=request.patient_attributes,
             surveyor_attributes=request.surveyor_attributes,
             surveyor_question_bank=request.surveyor_question_bank,
         )

backend/api/conversation_service.py

@@ -43,6 +43,7 @@ from .conversation_ws import ConnectionManager  # noqa: E402
 from .storage_service import get_run_store  # noqa: E402
 from backend.storage import RunRecord  # noqa: E402
 from backend.core.surveyor_knobs import compile_surveyor_attributes_overlay, compile_question_bank_overlay  # noqa: E402
+from backend.core.patient_knobs import compile_patient_attributes_overlay  # noqa: E402
 
 # Setup logging
 logger = logging.getLogger(__name__)
@@ -278,7 +279,7 @@ class ConversationInfo:
     message_count: int = 0
     task: Optional[asyncio.Task] = None
     stop_requested: bool = False
-    patient_prompt_addition: Optional[str] = None
+    patient_attributes: List[str] = field(default_factory=list)
     surveyor_attributes: List[str] = field(default_factory=list)
     surveyor_question_bank: Optional[str] = None
 
@@ -296,7 +297,7 @@ class HumanChatInfo:
     status: ConversationStatus
     created_at: datetime
     stop_requested: bool = False
-    patient_prompt_addition: Optional[str] = None
+    patient_attributes: List[str] = field(default_factory=list)
     surveyor_attributes: List[str] = field(default_factory=list)
     surveyor_question_bank: Optional[str] = None
     ai_role: str = "surveyor"  # "surveyor" or "patient"
@@ -339,7 +340,7 @@ class ConversationService:
         patient_persona_id: str,
         host: Optional[str] = None,
         model: Optional[str] = None,
-        patient_prompt_addition: Optional[str] = None,
+        patient_attributes: Optional[List[str]] = None,
         surveyor_attributes: Optional[List[str]] = None,
         surveyor_question_bank: Optional[str] = None,
         ai_role: Optional[str] = None,
@@ -368,7 +369,7 @@ class ConversationService:
             host=resolved_host,
             model=resolved_model,
             llm_backend=resolved_backend,
-            patient_prompt_addition=patient_prompt_addition,
+            patient_attributes=[s.strip() for s in (patient_attributes or []) if isinstance(s, str) and s.strip()],
             surveyor_attributes=[s.strip() for s in (surveyor_attributes or []) if isinstance(s, str) and s.strip()],
             surveyor_question_bank=surveyor_question_bank if isinstance(surveyor_question_bank, str) and surveyor_question_bank.strip() else None,
             ai_role=resolved_ai_role,
@@ -591,8 +592,10 @@ class ConversationService:
             patient_context = patient_persona.get("system_prompt", "") or ""
 
         patient_context = (patient_context or "").strip()
-        if chat_info.patient_prompt_addition:
-            patient_context = (patient_context + "\n\nAdditional patient context:\n" + chat_info.patient_prompt_addition).strip()
+        pat_lines = [s.strip() for s in (chat_info.patient_attributes or []) if isinstance(s, str) and s.strip()]
+        if pat_lines:
+            bullets = "\n".join(f"- {line}" for line in pat_lines)
+            patient_context = (patient_context + "\n\nPatient attributes (for context only):\n" + bullets).strip()
         if patient_context:
             system_prompt = (system_prompt + "\n\nPatient background (for context only):\n" + patient_context).strip()
 
@@ -651,8 +654,9 @@ class ConversationService:
         )
 
         system_prompt = (system_prompt or "").strip()
-        if chat_info.patient_prompt_addition:
-            system_prompt = (system_prompt + "\n\nAdditional instructions:\n" + chat_info.patient_prompt_addition).strip()
+        pat_attrs = compile_patient_attributes_overlay(chat_info.patient_attributes)
+        if pat_attrs:
+            system_prompt = (system_prompt + "\n\n" + pat_attrs).strip()
 
         response = await chat_info.client.generate(
             prompt=prompt_with_history,
@@ -668,7 +672,7 @@ class ConversationService:
                                patient_persona_id: str,
                                host: Optional[str] = None,
                                model: Optional[str] = None,
-                               patient_prompt_addition: Optional[str] = None,
+                               patient_attributes: Optional[List[str]] = None,
                                surveyor_attributes: Optional[List[str]] = None,
                                surveyor_question_bank: Optional[str] = None) -> bool:
         """Start a new AI-to-AI conversation.
@@ -712,7 +716,7 @@ class ConversationService:
                 host=resolved_host,
                 model=resolved_model,
                 llm_backend=resolved_backend,
-                patient_prompt_addition=patient_prompt_addition,
+                patient_attributes=[s.strip() for s in (patient_attributes or []) if isinstance(s, str) and s.strip()],
                 surveyor_attributes=[s.strip() for s in (surveyor_attributes or []) if isinstance(s, str) and s.strip()],
                 surveyor_question_bank=surveyor_question_bank if isinstance(surveyor_question_bank, str) and surveyor_question_bank.strip() else None,
                 status=ConversationStatus.STARTING,
@@ -735,7 +739,7 @@ class ConversationService:
                 model=resolved_model,
                 llm_backend=self.settings.llm.backend,
                 llm_parameters=llm_parameters,
-                patient_prompt_addition=patient_prompt_addition,
+                patient_attributes=[s.strip() for s in (patient_attributes or []) if isinstance(s, str) and s.strip()],
                 surveyor_attributes=[s.strip() for s in (surveyor_attributes or []) if isinstance(s, str) and s.strip()],
                 surveyor_question_bank=surveyor_question_bank if isinstance(surveyor_question_bank, str) else None,
             )
@@ -1006,7 +1010,7 @@ class ConversationService:
                     "personas": {
                         "surveyor_persona_id": conv_info.surveyor_persona_id,
                         "patient_persona_id": conv_info.patient_persona_id,
-                        "patient_prompt_addition": getattr(conv_info, "patient_prompt_addition", None),
+                        "patient_attributes": getattr(conv_info, "patient_attributes", None),
                         "surveyor_attributes": getattr(conv_info, "surveyor_attributes", None),
                         "surveyor_question_bank": getattr(conv_info, "surveyor_question_bank", None),
                         "asked_question_ids": asked_question_ids,

backend/api/conversation_ws.py

@@ -333,7 +333,7 @@ async def handle_start_conversation(data: dict, conversation_id: str):
         patient_persona_id = data.get("patient_persona_id")
         host = data.get("host")
         model = data.get("model")
-        patient_prompt_addition = data.get("patient_prompt_addition")
+        patient_attributes = data.get("patient_attributes")
         surveyor_attributes = data.get("surveyor_attributes")
         surveyor_question_bank = data.get("surveyor_question_bank")
 
@@ -352,7 +352,7 @@ async def handle_start_conversation(data: dict, conversation_id: str):
             patient_persona_id=patient_persona_id,
             host=host,
             model=model,
-            patient_prompt_addition=patient_prompt_addition,
+            patient_attributes=patient_attributes,
             surveyor_attributes=surveyor_attributes,
             surveyor_question_bank=surveyor_question_bank,
         )
@@ -387,7 +387,7 @@ async def handle_start_human_chat(data: dict, conversation_id: str):
         host = data.get("host")
         model = data.get("model")
         ai_role = data.get("ai_role")
-        patient_prompt_addition = data.get("patient_prompt_addition")
+        patient_attributes = data.get("patient_attributes")
         surveyor_attributes = data.get("surveyor_attributes")
         surveyor_question_bank = data.get("surveyor_question_bank")
 
@@ -405,7 +405,7 @@ async def handle_start_human_chat(data: dict, conversation_id: str):
             patient_persona_id=patient_persona_id,
             host=host,
             model=model,
-            patient_prompt_addition=patient_prompt_addition,
+            patient_attributes=patient_attributes,
             surveyor_attributes=surveyor_attributes,
             surveyor_question_bank=surveyor_question_bank,
             ai_role=ai_role,

backend/core/conversation_manager.py

@@ -32,6 +32,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 from backend.core.llm_client import create_llm_client
 from backend.core.persona_system import PersonaSystem
 from backend.core.surveyor_knobs import compile_surveyor_attributes_overlay, compile_question_bank_overlay
+from backend.core.patient_knobs import compile_patient_attributes_overlay
 
 SURVEYOR_MAX_TOKENS = 140
 PATIENT_MAX_TOKENS = 240
@@ -80,7 +81,7 @@ class ConversationManager:
                  patient_persona_id: str = None,
                  surveyor_persona: dict = None,
                  patient_persona: dict = None,
-                 patient_prompt_addition: Optional[str] = None,
+                 patient_attributes: Optional[List[str]] = None,
                  surveyor_attributes: Optional[List[str]] = None,
                  surveyor_question_bank: Optional[str] = None,
                  host: str = "http://localhost:11434",
@@ -129,7 +130,7 @@ class ConversationManager:
         self.state = ConversationState.INITIALIZED
         self.history: List[Dict] = []
         self.turn_count = 0
-        self.patient_prompt_addition = (patient_prompt_addition or "").strip()
+        self.patient_attributes = [s.strip() for s in (patient_attributes or []) if isinstance(s, str) and s.strip()]
         self.surveyor_attributes = [s.strip() for s in (surveyor_attributes or []) if isinstance(s, str) and s.strip()]
         self.surveyor_question_bank = (surveyor_question_bank or "").strip() or None
         self.asked_question_ids: List[str] = []
@@ -329,8 +330,9 @@ class ConversationManager:
                 conversation_history=conversation_history,
                 user_prompt=user_prompt
             )
-            if self.patient_prompt_addition:
-                system_prompt = f"{system_prompt}\n\nAdditional instructions:\n{self.patient_prompt_addition}"
+            attrs = compile_patient_attributes_overlay(self.patient_attributes)
+            if attrs:
+                system_prompt = f"{system_prompt}\n\n{attrs}"
 
             # Generate response
             response = await self.client.generate(

backend/core/patient_knobs.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def compile_patient_attributes_overlay(attributes: Any) -> str:
+    if not isinstance(attributes, list):
+        return ""
+    cleaned = [s.strip() for s in attributes if isinstance(s, str) and s.strip()]
+    if not cleaned:
+        return ""
+    bullets = "\n".join(f"- {line}" for line in cleaned)
+    return "Continue the conversation following these patient attributes:\n" + bullets
+

docs/persona-knobs.md

@@ -56,9 +56,6 @@ A list of survey questions the surveyor must work through.
 
 When a question bank is present, the surveyor outputs strict JSON including the chosen question id (e.g., `q01`) so asked questions can be tracked deterministically.
 
-### Surveyor prompt addition (optional, per-run)
-Additional free-form instructions appended last (lowest priority).
-
 ---
 
 ## Patient controls (Core v1, minimal)
@@ -69,8 +66,8 @@ Patient structured controls are intentionally minimal for now; the synthetic pat
 - `name` (required): display name.
 - `description` (optional): short one-liner shown in selectors.
 
-### Patient prompt addition (optional, per-run)
-Patient prompt addition is supported as a run-level override.
+### Attributes (plain bullet lines)
+A list of short rules the patient should follow during the session, compiled into the patient prompt so the control always matters.
 
 ---
 

docs/roadmap.md

@@ -63,7 +63,7 @@ _Last updated: 2026-01-22_
      - Follow-ups:
        - Improve Human-to-AI turn-taking clarity (make it obvious who should speak next, especially when AI role = Patient).
        - Make persona ids backend-oriented and avoid showing raw ids in user-facing dropdowns (prefer friendly display names only).
-   - **9.2 Patient controls v1**: patient prompt addition + (optional) patient attributes list (local-first).
+   - **9.2 Patient controls v1 (Attributes list)**: patient persona attributes (local-first, compiled into the patient prompt).
    - **9.3 Analysis Agent controls v1**: show effective template + allow selecting template (read-only if templates aren’t CRUD yet).
    - **9.4 System controls v1**: show effective runtime config (LLM backend/model, DB path, auth status) as read-only “Effective settings”.
    - **9.5 Validation + guardrails**: schema versioning, reset-to-defaults, and explicit “applies next run” UX.

frontend/pages/config_view.py

@@ -32,9 +32,15 @@ def get_config_view_js() -> str:
 		                }
 		                return [];
 		            });
-		            const [patientPromptAddition, setPatientPromptAddition] = React.useState(() => {
+		            const [patientAttributeItems, setPatientAttributeItems] = React.useState(() => {
 		                const data = getPatientPersonaData(existing || {}, initialEditorPatientId) || {};
-		                return (typeof data.prompt_addition === 'string') ? data.prompt_addition : '';
+		                const attrs = Array.isArray(data.attributes) ? data.attributes : null;
+		                if (attrs && attrs.length) {
+		                    return attrs
+		                        .map((x) => (typeof x === 'string' ? x.trim() : ''))
+		                        .filter((x) => x.length > 0);
+		                }
+		                return [];
 		            });
 		            const [savedAt, setSavedAt] = React.useState(existing?.saved_at || null);
 		            const [saveFlash, setSaveFlash] = React.useState(false);
@@ -71,6 +77,18 @@ def get_config_view_js() -> str:
 	                setSurveyorAttributeItems((prev) => (prev || []).filter((_, i) => i !== idx));
 	            };
 
+	            const addPatientAttribute = () => {
+	                setPatientAttributeItems((prev) => ([...(prev || []), '' ]));
+	            };
+
+	            const updatePatientAttribute = (idx, text) => {
+	                setPatientAttributeItems((prev) => (prev || []).map((v, i) => (i === idx ? text : v)));
+	            };
+
+	            const removePatientAttribute = (idx) => {
+	                setPatientAttributeItems((prev) => (prev || []).filter((_, i) => i !== idx));
+	            };
+
             React.useEffect(() => {
                 authedFetch('/api/personas')
                     .then(r => r.json())
@@ -104,7 +122,8 @@ def get_config_view_js() -> str:
 	            React.useEffect(() => {
 	                const cfg = loadConfig() || {};
 	                const data = getPatientPersonaData(cfg, selectedPatientId) || {};
-	                setPatientPromptAddition((typeof data.prompt_addition === 'string') ? data.prompt_addition : '');
+	                const attrs = Array.isArray(data.attributes) ? data.attributes : [];
+	                setPatientAttributeItems(attrs.map((x) => (typeof x === 'string' ? x.trim() : '')).filter((x) => x.length > 0));
 	            }, [selectedPatientId]);
 
 		            const onSave = () => {
@@ -123,7 +142,9 @@ def get_config_view_js() -> str:
 		                };
 
 		                patientStore[selectedPatientId] = {
-		                    prompt_addition: (patientPromptAddition || '')
+		                    attributes: (patientAttributeItems || [])
+		                        .map((x) => (typeof x === 'string' ? x.trim() : ''))
+		                        .filter((x) => x.length > 0),
 		                };
 
 		                const cfg = Object.assign({}, prev, {
@@ -267,8 +288,8 @@ def get_config_view_js() -> str:
 	                            </div>
 	                        </div>
 	                    ) : activePane === 'patients' ? (
-                        <div className="mt-6 grid grid-cols-2 gap-6">
-                            <div>
+                        <div className="mt-6">
+                            <div className="mb-4">
 	                                <label className="block text-sm font-semibold text-slate-700 mb-2">Edit patient persona</label>
                                 <select
                                     className="w-full border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white"
@@ -279,18 +300,51 @@ def get_config_view_js() -> str:
 	                                        <option key={p.id} value={p.id}>{p.name}</option>
 	                                    ))}
                                 </select>
+                            </div>
 
-	                                <label className="block text-sm font-semibold text-slate-700 mt-4 mb-2">Patient prompt addition (optional)</label>
-	                                <textarea
-	                                    className="w-full border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white h-28"
-	                                    placeholder="Extra context for this patient persona (used when the patient persona is selected in a run)."
-	                                    value={patientPromptAddition}
-	                                    onChange={(e) => setPatientPromptAddition(e.target.value)}
-	                                />
+                            <div className="grid grid-cols-2 gap-6">
+                                <div>
+                                    <label className="block text-sm font-semibold text-slate-700 mb-2">Attributes</label>
+                                    <div className="text-xs text-slate-500 mb-2">
+                                        Plain-language rules the patient should follow during the session.
+                                    </div>
+                                    <div className="space-y-2">
+                                        {(patientAttributeItems || []).length === 0 ? (
+                                            <div className="text-sm text-slate-500">No attributes yet.</div>
+                                        ) : (
+                                            (patientAttributeItems || []).map((attr, idx) => (
+                                                <div key={idx} className="flex items-start gap-2">
+                                                    <div className="mt-2 text-xs font-mono text-slate-500 w-10 shrink-0">{String(idx + 1).padStart(2, '0')}</div>
+                                                    <input
+                                                        className="flex-1 border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white"
+                                                        value={attr || ''}
+                                                        onChange={(e) => updatePatientAttribute(idx, e.target.value)}
+                                                        placeholder="Type an attribute..."
+                                                    />
+                                                    <button
+                                                        type="button"
+                                                        onClick={() => removePatientAttribute(idx)}
+                                                        className="text-slate-600 hover:text-red-600 px-2 py-2 text-sm"
+                                                        title="Remove attribute"
+                                                    >
+                                                        ✕
+                                                    </button>
+                                                </div>
+                                            ))
+                                        )}
+                                        <button
+                                            type="button"
+                                            onClick={addPatientAttribute}
+                                            className="bg-slate-100 hover:bg-slate-200 text-slate-800 px-3 py-2 rounded-lg text-sm font-semibold transition-all border border-slate-300"
+                                        >
+                                            + Add attribute
+                                        </button>
+                                    </div>
+                                </div>
+                                <div className="text-sm text-slate-600">
+                                    These attributes are compiled into the patient prompt for the next run when this patient persona is selected.
+                                </div>
                             </div>
-	                            <div className="text-sm text-slate-600">
-	                                Patient structured controls are not implemented yet; this field is a per-patient freeform override used for context.
-	                            </div>
                         </div>
                     ) : activePane === 'analysis' ? (
                         <div className="mt-6 text-sm text-slate-600">

frontend/pages/main_page.py

@@ -76,12 +76,6 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 	            const store = getPatientPersonaStore(cfg);
 	            const data = store[patientId];
 	            if (data && typeof data === 'object') return data;
-	
-	            // Backward compatibility: legacy global field tied to `cfg.patient_persona_id`.
-	            const legacyId = cfg && cfg.patient_persona_id;
-	            if (legacyId === patientId && typeof cfg.patient_prompt_addition === 'string') {
-	                return { prompt_addition: cfg.patient_prompt_addition };
-	            }
 	            return null;
 	        }
 
@@ -104,10 +98,12 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 	                .filter((x) => x.length > 0);
 	        }
 
-	        function getPatientPromptAdditionFor(cfg, patientId) {
+	        function getPatientAttributesFor(cfg, patientId) {
 	            const data = getPatientPersonaData(cfg, patientId) || {};
-	            const raw = (typeof data.prompt_addition === 'string') ? data.prompt_addition : '';
-	            return raw || '';
+	            const attrs = Array.isArray(data.attributes) ? data.attributes : [];
+	            return attrs
+	                .map((x) => (typeof x === 'string') ? x.trim() : '')
+	                .filter((x) => x.length > 0);
 	        }
 
 	        function getRunPersonaSelection(cfg, kind) {
@@ -678,7 +674,7 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 	                const cfg = loadConfig() || {};
 	                const surveyorQuestionBank = getSurveyorQuestionBankFor(cfg, surveyorId);
 	                const surveyorAttributes = getSurveyorAttributesFor(cfg, surveyorId);
-	                const patientPromptAddition = getPatientPromptAdditionFor(cfg, patientId);
+	                const patientAttributes = getPatientAttributesFor(cfg, patientId);
 
                 setTimeout(() => {
                     if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
@@ -688,7 +684,7 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 	                            patient_persona_id: patientId,
 	                            surveyor_question_bank: surveyorQuestionBank || undefined,
 	                            surveyor_attributes: surveyorAttributes.length ? surveyorAttributes : undefined,
-	                            patient_prompt_addition: patientPromptAddition || undefined,
+	                            patient_attributes: patientAttributes.length ? patientAttributes : undefined,
 	                        }));
 	                    }
 	                }, 500);
@@ -710,7 +706,7 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 	                const cfg = loadConfig() || {};
 	                const surveyorQuestionBank = getSurveyorQuestionBankFor(cfg, surveyorId);
 	                const surveyorAttributes = getSurveyorAttributesFor(cfg, surveyorId);
-	                const patientPromptAddition = getPatientPromptAdditionFor(cfg, patientId);
+	                const patientAttributes = getPatientAttributesFor(cfg, patientId);
 
                 setTimeout(() => {
                     if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
@@ -721,7 +717,7 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
 	                            patient_persona_id: patientId,
 	                            surveyor_question_bank: surveyorQuestionBank || undefined,
 	                            surveyor_attributes: surveyorAttributes.length ? surveyorAttributes : undefined,
-	                            patient_prompt_addition: patientPromptAddition || undefined,
+	                            patient_attributes: patientAttributes.length ? patientAttributes : undefined,
 	                        }));
 	                    }
 	                }, 500);

frontend/react_gradio_hybrid.py

@@ -166,7 +166,7 @@ async def frontend_websocket(websocket: WebSocket, conversation_id: str):
                         "patient_persona_id": data.get("patient_persona_id", "cooperative_senior_001"),
                         "surveyor_question_bank": data.get("surveyor_question_bank"),
                         "surveyor_attributes": data.get("surveyor_attributes"),
-                        "patient_prompt_addition": data.get("patient_prompt_addition"),
+                        "patient_attributes": data.get("patient_attributes"),
                         "host": settings.llm.host,
                         "model": settings.llm.model,
                     })
@@ -190,7 +190,7 @@ async def frontend_websocket(websocket: WebSocket, conversation_id: str):
                         "patient_persona_id": data.get("patient_persona_id", "cooperative_senior_001"),
                         "surveyor_question_bank": data.get("surveyor_question_bank"),
                         "surveyor_attributes": data.get("surveyor_attributes"),
-                        "patient_prompt_addition": data.get("patient_prompt_addition"),
+                        "patient_attributes": data.get("patient_attributes"),
                         "host": settings.llm.host,
                         "model": settings.llm.model,
                     })