Feat: surveyor core knobs (compiled prompt + UI)

backend/api/conversation_routes.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, Optional
+from typing import Dict, Optional, Any
 
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
@@ -26,6 +26,10 @@ class StartConversationRequest(BaseModel):
         default=None,
         description="Extra instructions appended to the patient system prompt for this run",
     )
+    surveyor_knobs: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Structured surveyor configuration knobs (compiled into the surveyor system prompt)",
+    )
 
 
 class ConversationStatusResponse(BaseModel):
@@ -49,6 +53,7 @@ async def start_conversation(request: StartConversationRequest) -> Dict[str, str
             model=request.model,
             surveyor_prompt_addition=request.surveyor_prompt_addition,
             patient_prompt_addition=request.patient_prompt_addition,
+            surveyor_knobs=request.surveyor_knobs,
         )
         if success:
             return {"message": "Conversation started successfully", "conversation_id": request.conversation_id}
@@ -94,4 +99,3 @@ async def list_conversations() -> Dict[str, Dict]:
         return await service.list_active_conversations()
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Internal error listing conversations: {str(e)}")
-

backend/api/conversation_service.py

@@ -42,6 +42,7 @@ from backend.core.persona_system import PersonaSystem  # noqa: E402
 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_overlay  # noqa: E402
 
 # Setup logging
 logger = logging.getLogger(__name__)
@@ -271,6 +272,7 @@ class ConversationInfo:
     stop_requested: bool = False
     surveyor_prompt_addition: Optional[str] = None
     patient_prompt_addition: Optional[str] = None
+    surveyor_knobs: Optional[Dict[str, Any]] = None
 
 
 @dataclass
@@ -288,6 +290,7 @@ class HumanChatInfo:
     stop_requested: bool = False
     surveyor_prompt_addition: Optional[str] = None
     patient_prompt_addition: Optional[str] = None
+    surveyor_knobs: Optional[Dict[str, Any]] = None
     lock: asyncio.Lock = field(default_factory=asyncio.Lock)
     client: Any = None
 
@@ -328,6 +331,7 @@ class ConversationService:
         model: Optional[str] = None,
         surveyor_prompt_addition: Optional[str] = None,
         patient_prompt_addition: Optional[str] = None,
+        surveyor_knobs: Optional[Dict[str, Any]] = None,
     ) -> bool:
         """Start a new human-to-surveyor chat session."""
         if conversation_id in self.active_conversations or conversation_id in self.active_human_chats:
@@ -353,6 +357,7 @@ class ConversationService:
             llm_backend=resolved_backend,
             surveyor_prompt_addition=surveyor_prompt_addition,
             patient_prompt_addition=patient_prompt_addition,
+            surveyor_knobs=surveyor_knobs if isinstance(surveyor_knobs, dict) else None,
             status=ConversationStatus.STARTING,
             created_at=datetime.now(),
         )
@@ -501,6 +506,10 @@ class ConversationService:
             user_prompt=user_prompt,
         )
 
+        overlay = compile_surveyor_overlay(chat_info.surveyor_knobs)
+        if overlay:
+            system_prompt = (system_prompt + "\n\n" + overlay).strip()
+
         patient_persona = self.persona_system.get_persona(chat_info.patient_persona_id) or {}
         try:
             patient_context = self.persona_system.prompt_builder.build_system_prompt(patient_persona)
@@ -532,7 +541,8 @@ class ConversationService:
                                host: Optional[str] = None,
                                model: Optional[str] = None,
                                surveyor_prompt_addition: Optional[str] = None,
-                               patient_prompt_addition: Optional[str] = None) -> bool:
+                               patient_prompt_addition: Optional[str] = None,
+                               surveyor_knobs: Optional[Dict[str, Any]] = None) -> bool:
         """Start a new AI-to-AI conversation.
 
         Args:
@@ -576,6 +586,7 @@ class ConversationService:
                 llm_backend=resolved_backend,
                 surveyor_prompt_addition=surveyor_prompt_addition,
                 patient_prompt_addition=patient_prompt_addition,
+                surveyor_knobs=surveyor_knobs if isinstance(surveyor_knobs, dict) else None,
                 status=ConversationStatus.STARTING,
                 created_at=datetime.now()
             )
@@ -598,6 +609,7 @@ class ConversationService:
                 llm_parameters=llm_parameters,
                 surveyor_prompt_addition=surveyor_prompt_addition,
                 patient_prompt_addition=patient_prompt_addition,
+                surveyor_knobs=surveyor_knobs if isinstance(surveyor_knobs, dict) else None,
             )
 
             # Start conversation streaming task
@@ -863,6 +875,7 @@ class ConversationService:
                         "patient_persona_id": conv_info.patient_persona_id,
                         "surveyor_prompt_addition": getattr(conv_info, "surveyor_prompt_addition", None),
                         "patient_prompt_addition": getattr(conv_info, "patient_prompt_addition", None),
+                        "surveyor_knobs": getattr(conv_info, "surveyor_knobs", None),
                     },
                 }
 

backend/api/conversation_ws.py

@@ -335,6 +335,7 @@ async def handle_start_conversation(data: dict, conversation_id: str):
         model = data.get("model")
         surveyor_prompt_addition = data.get("surveyor_prompt_addition")
         patient_prompt_addition = data.get("patient_prompt_addition")
+        surveyor_knobs = data.get("surveyor_knobs")
 
         if not surveyor_persona_id or not patient_persona_id:
             await manager.send_to_conversation(conversation_id, {
@@ -353,6 +354,7 @@ async def handle_start_conversation(data: dict, conversation_id: str):
             model=model,
             surveyor_prompt_addition=surveyor_prompt_addition,
             patient_prompt_addition=patient_prompt_addition,
+            surveyor_knobs=surveyor_knobs,
         )
 
         if success:
@@ -386,6 +388,7 @@ async def handle_start_human_chat(data: dict, conversation_id: str):
         model = data.get("model")
         surveyor_prompt_addition = data.get("surveyor_prompt_addition")
         patient_prompt_addition = data.get("patient_prompt_addition")
+        surveyor_knobs = data.get("surveyor_knobs")
 
         if not surveyor_persona_id or not patient_persona_id:
             await manager.send_to_conversation(conversation_id, {
@@ -403,6 +406,7 @@ async def handle_start_human_chat(data: dict, conversation_id: str):
             model=model,
             surveyor_prompt_addition=surveyor_prompt_addition,
             patient_prompt_addition=patient_prompt_addition,
+            surveyor_knobs=surveyor_knobs,
         )
 
         if success:

backend/core/conversation_manager.py

@@ -31,6 +31,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_overlay
 
 SURVEYOR_MAX_TOKENS = 140
 PATIENT_MAX_TOKENS = 240
@@ -81,6 +82,7 @@ class ConversationManager:
                  patient_persona: dict = None,
                  surveyor_prompt_addition: Optional[str] = None,
                  patient_prompt_addition: Optional[str] = None,
+                 surveyor_knobs: Optional[Dict[str, Any]] = None,
                  host: str = "http://localhost:11434",
                  model: str = "llama3.2:latest",
                  llm_backend: str = "ollama",
@@ -129,6 +131,7 @@ class ConversationManager:
         self.turn_count = 0
         self.surveyor_prompt_addition = (surveyor_prompt_addition or "").strip()
         self.patient_prompt_addition = (patient_prompt_addition or "").strip()
+        self.surveyor_knobs = surveyor_knobs if isinstance(surveyor_knobs, dict) else None
         
     def _generate_conversation_id(self) -> str:
         """Generate unique conversation identifier."""
@@ -214,6 +217,9 @@ class ConversationManager:
                 conversation_history=conversation_history,
                 user_prompt=user_prompt
             )
+            overlay = compile_surveyor_overlay(self.surveyor_knobs)
+            if overlay:
+                system_prompt = f"{system_prompt}\n\n{overlay}"
             if self.surveyor_prompt_addition:
                 system_prompt = f"{system_prompt}\n\nAdditional instructions:\n{self.surveyor_prompt_addition}"
 

backend/core/surveyor_knobs.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+def _as_str_list(value: Any) -> List[str]:
+    if not value:
+        return []
+    if isinstance(value, list):
+        out: List[str] = []
+        for item in value:
+            if isinstance(item, str) and item.strip():
+                out.append(item.strip())
+        return out
+    return []
+
+
+def compile_surveyor_overlay(knobs: Optional[Dict[str, Any]]) -> str:
+    """Compile structured surveyor knobs into a deterministic prompt overlay."""
+    if not isinstance(knobs, dict) or not knobs:
+        return ""
+
+    stance = knobs.get("stance")
+    question_strategy = knobs.get("question_strategy")
+    empathy_style = knobs.get("empathy_style")
+    off_track_handling = knobs.get("off_track_handling")
+
+    probing_policy = _as_str_list(knobs.get("probing_policy"))
+    sensitivity_handling = _as_str_list(knobs.get("sensitivity_handling"))
+
+    lines: List[str] = []
+    lines.append("Surveyor configuration (structured knobs):")
+
+    def add(label: str, value: Any):
+        if isinstance(value, str) and value.strip():
+            lines.append(f"- {label}: {value.strip()}")
+
+    add("stance", stance)
+    add("question_strategy", question_strategy)
+    add("empathy_style", empathy_style)
+    add("off_track_handling", off_track_handling)
+
+    if probing_policy:
+        lines.append("- probing_policy:")
+        for item in probing_policy:
+            lines.append(f"  - {item}")
+
+    if sensitivity_handling:
+        lines.append("- sensitivity_handling:")
+        for item in sensitivity_handling:
+            lines.append(f"  - {item}")
+
+    return "\n".join(lines).strip()
+

docs/development.md

@@ -74,6 +74,7 @@ The UI also includes a **Configuration** view that lets you select personas and
 - No automated test suite yet. Add lightweight `pytest` modules under `tests/` as you extend functionality.
 - Manually verify through the primary web UI (`frontend/react_gradio_hybrid.py`).
 - For persistence + history: complete a run, confirm it appears in **History**, restart the container, and confirm it still appears and exports download.
+- For config knobs (surveyor v1): change surveyor settings in **Configuration**, run an AI↔AI session, and confirm behavior differs and the completed run’s `config.personas.surveyor_knobs` is present when fetched from `/api/runs/{run_id}`.
 - If you need to debug the conversation loop, instrument `backend/core/conversation_manager.py` or launch a shell and run it directly.
 
 ## Notes on Persistence (HF)

frontend/pages/config_view.py

@@ -8,6 +8,14 @@ def get_config_view_js() -> str:
             const [selectedPatientId, setSelectedPatientId] = React.useState(existing?.patient_persona_id || 'cooperative_senior_001');
             const [surveyorPromptAddition, setSurveyorPromptAddition] = React.useState(existing?.surveyor_prompt_addition || '');
             const [patientPromptAddition, setPatientPromptAddition] = React.useState(existing?.patient_prompt_addition || '');
+            const [surveyorKnobs, setSurveyorKnobs] = React.useState(existing?.surveyor_knobs || {
+                stance: 'empathetic_researcher',
+                question_strategy: 'conversational_cover_all',
+                probing_policy: ['reflect_emotion', 'summarize_and_confirm'],
+                empathy_style: 'validating',
+                off_track_handling: 'gentle_redirect',
+                sensitivity_handling: ['acknowledge', 'normalize', 'avoid_advice']
+            });
             const [savedAt, setSavedAt] = React.useState(existing?.saved_at || null);
 
             React.useEffect(() => {
@@ -28,6 +36,7 @@ def get_config_view_js() -> str:
                     patient_persona_id: selectedPatientId,
                     surveyor_prompt_addition: surveyorPromptAddition,
                     patient_prompt_addition: patientPromptAddition,
+                    surveyor_knobs: surveyorKnobs,
                     saved_at: new Date().toISOString()
                 };
                 localStorage.setItem(STORAGE_KEY, JSON.stringify(cfg));
@@ -58,6 +67,105 @@ def get_config_view_js() -> str:
                                 ))}
                             </select>
 
+                            <div className="mt-4">
+                                <label className="block text-sm font-semibold text-slate-700 mb-2">Surveyor stance</label>
+                                <select
+                                    className="w-full border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white"
+                                    value={surveyorKnobs.stance || 'empathetic_researcher'}
+                                    onChange={(e) => setSurveyorKnobs(prev => Object.assign({}, prev, { stance: e.target.value }))}
+                                >
+                                    <option value="empathetic_researcher">Empathetic researcher</option>
+                                    <option value="neutral_clinical">Neutral clinical</option>
+                                    <option value="time_efficient">Time efficient</option>
+                                </select>
+                            </div>
+
+                            <div className="mt-4">
+                                <label className="block text-sm font-semibold text-slate-700 mb-2">Question strategy</label>
+                                <select
+                                    className="w-full border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white"
+                                    value={surveyorKnobs.question_strategy || 'conversational_cover_all'}
+                                    onChange={(e) => setSurveyorKnobs(prev => Object.assign({}, prev, { question_strategy: e.target.value }))}
+                                >
+                                    <option value="sequential">Sequential</option>
+                                    <option value="adaptive_followups">Adaptive with follow-ups</option>
+                                    <option value="conversational_cover_all">Conversational but cover all</option>
+                                </select>
+                            </div>
+
+                            <div className="mt-4">
+                                <label className="block text-sm font-semibold text-slate-700 mb-2">Empathy style</label>
+                                <select
+                                    className="w-full border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white"
+                                    value={surveyorKnobs.empathy_style || 'validating'}
+                                    onChange={(e) => setSurveyorKnobs(prev => Object.assign({}, prev, { empathy_style: e.target.value }))}
+                                >
+                                    <option value="validating">Validating</option>
+                                    <option value="neutral">Neutral</option>
+                                    <option value="supportive_brief">Supportive, brief</option>
+                                </select>
+                            </div>
+
+                            <div className="mt-4">
+                                <label className="block text-sm font-semibold text-slate-700 mb-2">Off-track handling</label>
+                                <select
+                                    className="w-full border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white"
+                                    value={surveyorKnobs.off_track_handling || 'gentle_redirect'}
+                                    onChange={(e) => setSurveyorKnobs(prev => Object.assign({}, prev, { off_track_handling: e.target.value }))}
+                                >
+                                    <option value="gentle_redirect">Gently redirect</option>
+                                    <option value="one_vent_then_redirect">Let them vent once, then redirect</option>
+                                    <option value="hard_redirect">Hard redirect</option>
+                                </select>
+                            </div>
+
+                            <div className="mt-4">
+                                <label className="block text-sm font-semibold text-slate-700 mb-2">Probing policy</label>
+                                {[
+                                    { key: 'clarify_timeline', label: 'Clarify timeline' },
+                                    { key: 'ask_examples', label: 'Ask examples' },
+                                    { key: 'quantify_frequency_severity', label: 'Quantify frequency/severity' },
+                                    { key: 'reflect_emotion', label: 'Reflect emotion' },
+                                    { key: 'summarize_and_confirm', label: 'Summarize and confirm' }
+                                ].map((item) => (
+                                    <label key={item.key} className="flex items-center gap-2 text-sm text-slate-700 mt-1">
+                                        <input
+                                            type="checkbox"
+                                            checked={(surveyorKnobs.probing_policy || []).includes(item.key)}
+                                            onChange={(e) => {
+                                                const next = new Set(surveyorKnobs.probing_policy || []);
+                                                if (e.target.checked) next.add(item.key); else next.delete(item.key);
+                                                setSurveyorKnobs(prev => Object.assign({}, prev, { probing_policy: Array.from(next) }));
+                                            }}
+                                        />
+                                        {item.label}
+                                    </label>
+                                ))}
+                            </div>
+
+                            <div className="mt-4">
+                                <label className="block text-sm font-semibold text-slate-700 mb-2">Sensitivity handling</label>
+                                {[
+                                    { key: 'acknowledge', label: 'Acknowledge' },
+                                    { key: 'offer_skip', label: 'Offer to skip' },
+                                    { key: 'normalize', label: 'Normalize' },
+                                    { key: 'avoid_advice', label: 'Avoid advice' }
+                                ].map((item) => (
+                                    <label key={item.key} className="flex items-center gap-2 text-sm text-slate-700 mt-1">
+                                        <input
+                                            type="checkbox"
+                                            checked={(surveyorKnobs.sensitivity_handling || []).includes(item.key)}
+                                            onChange={(e) => {
+                                                const next = new Set(surveyorKnobs.sensitivity_handling || []);
+                                                if (e.target.checked) next.add(item.key); else next.delete(item.key);
+                                                setSurveyorKnobs(prev => Object.assign({}, prev, { sensitivity_handling: Array.from(next) }));
+                                            }}
+                                        />
+                                        {item.label}
+                                    </label>
+                                ))}
+                            </div>
+
                             <label className="block text-sm font-semibold text-slate-700 mt-4 mb-2">Surveyor prompt addition (optional)</label>
                             <textarea
                                 className="w-full border border-slate-300 rounded-lg px-3 py-2 text-sm bg-white h-28"
@@ -86,6 +194,36 @@ def get_config_view_js() -> str:
                                 value={patientPromptAddition}
                                 onChange={(e) => setPatientPromptAddition(e.target.value)}
                             />
+
+                            <div className="mt-6">
+                                <label className="block text-sm font-semibold text-slate-700 mb-2">Surveyor prompt preview</label>
+                                <div className="text-xs text-slate-500 mb-2">
+                                    Best-effort preview; the backend compiles knobs into the surveyor system prompt at runtime.
+                                </div>
+                                <pre className="w-full whitespace-pre-wrap text-xs border border-slate-200 rounded-lg bg-slate-50 p-3 max-h-64 overflow-auto">
+{(() => {
+    const p = (personas.surveyors || []).find(x => x.id === selectedSurveyorId);
+    const base = (p && p.system_prompt) ? p.system_prompt : '';
+    const lines = [];
+    lines.push('Surveyor configuration (structured knobs):');
+    if (surveyorKnobs?.stance) lines.push(`- stance: ${surveyorKnobs.stance}`);
+    if (surveyorKnobs?.question_strategy) lines.push(`- question_strategy: ${surveyorKnobs.question_strategy}`);
+    if (surveyorKnobs?.empathy_style) lines.push(`- empathy_style: ${surveyorKnobs.empathy_style}`);
+    if (surveyorKnobs?.off_track_handling) lines.push(`- off_track_handling: ${surveyorKnobs.off_track_handling}`);
+    if ((surveyorKnobs?.probing_policy || []).length) {
+        lines.push('- probing_policy:');
+        (surveyorKnobs.probing_policy || []).forEach((k) => lines.push(`  - ${k}`));
+    }
+    if ((surveyorKnobs?.sensitivity_handling || []).length) {
+        lines.push('- sensitivity_handling:');
+        (surveyorKnobs.sensitivity_handling || []).forEach((k) => lines.push(`  - ${k}`));
+    }
+    const overlay = lines.join('\n');
+    const addition = (surveyorPromptAddition || '').trim();
+    return [base.trim(), overlay.trim(), addition ? `Additional instructions:\n${addition}` : ''].filter(Boolean).join('\n\n');
+})()}
+                                </pre>
+                            </div>
                         </div>
                     </div>
 

frontend/pages/main_page.py

@@ -537,7 +537,8 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
                             surveyor_persona_id: surveyorId,
                             patient_persona_id: patientId,
                             surveyor_prompt_addition: cfg.surveyor_prompt_addition || undefined,
-                            patient_prompt_addition: cfg.patient_prompt_addition || undefined
+                            patient_prompt_addition: cfg.patient_prompt_addition || undefined,
+                            surveyor_knobs: cfg.surveyor_knobs || undefined
                         }));
                     }
                 }, 500);
@@ -566,7 +567,8 @@ def get_main_page_html(auth_enabled: bool = False) -> str:
                             surveyor_persona_id: surveyorId,
                             patient_persona_id: patientId,
                             surveyor_prompt_addition: cfg.surveyor_prompt_addition || undefined,
-                            patient_prompt_addition: cfg.patient_prompt_addition || undefined
+                            patient_prompt_addition: cfg.patient_prompt_addition || undefined,
+                            surveyor_knobs: cfg.surveyor_knobs || undefined
                         }));
                     }
                 }, 500);