feat: Automated Simulation with Web Search Persona Research

[mathaix]

Summary

• Add automated interview simulation where an AI persona plays the interviewee role
• Integrate Claude web search to research company products from provided URL (e.g., facebook.com → learns about Instagram, Meta products)
• Display prominent persona card during simulation showing role, experience, company, and communication style
• Add "Auto-Simulate" button to project detail page for each configured agent

Features

Backend (simulation_agent.py, simulation_sessions.py)

• search_company_products() - Uses Claude with web search tool to research company
• gather_company_context() - Combines web search + website scraping in parallel
• New API endpoints: POST /auto, POST /auto/from-design-session/{id}, POST /{id}/run-auto
• PersonaConfig with role, name, company_url, experience_years, communication_style

Frontend (AutomatedSimulationPage.tsx)

• Persona configuration form (role, name, company URL, experience, style)
• Model selection (Haiku/Sonnet/Opus) and conversation turns slider
• Streaming conversation view with interviewer/interviewee messages
• Active persona card displayed during simulation

Test plan

• Navigate to project with a blueprint
• Click "Auto-Simulate" on an agent card
• Configure persona with role (e.g., "Product Manager for Instagram")
• Add company URL (e.g., https://facebook.com)
• Start simulation and verify web search gathers company context
• Confirm persona card displays during conversation
• Verify streaming messages show correctly for both interviewer and interviewee

🤖 Generated with Claude Code

[claude]

Pull Request Review: Automated Simulation with Web Search Persona Research

Thank you for this feature addition! This is a significant enhancement that adds AI-powered persona simulation with web search capabilities.

✅ Strengths

Code Quality

• Well-structured architecture with clear separation of concerns
• Parallel execution using asyncio.gather() for web search and website fetching
• Comprehensive error handling with graceful degradation
• Strong typing with Pydantic models for validation
• Clean RESTful API design

Security

• Input sanitization via InputSanitizer.sanitize_system_prompt()
• URL validation with protocol checks
• Field validation with whitelisting
• Bounded inputs (experience_years 0-50, num_turns 1-20)

User Experience

• Real-time streaming provides excellent feedback
• Persona card display improves context awareness
• Flexible configuration (custom prompt vs. design session)
• Proper session cleanup on unmount

⚠️ Issues & Recommendations

1. Missing Test Coverage (Critical)

No tests for new core functionality: search_company_products(), gather_company_context(), extract_company_name_from_url(), and new API endpoints.

Per CLAUDE.md testing guidelines, comprehensive test coverage is required before merge.

2. API Key Exposure Risk (High)

Location: simulation_agent.py:538

Direct instantiation of anthropic.Anthropic() without validation. Should use centralized config (clara.config) and validate API key presence before making calls.

3. Hardcoded Model Version (Medium)

Location: simulation_agent.py:559

Model version claude-sonnet-4-20250514 is hardcoded. Extract to module constant or config.

4. Insufficient Error Context (Medium)

Location: simulation_agent.py:577-582

Error messages could expose sensitive info. Use type(e).name and provide sanitized user-facing messages while logging details server-side.

5. Race Condition in Message Streaming (Low-Medium)

Location: AutomatedSimulationPage.tsx:132-150

Date.now() for message IDs could collide. Use counter or crypto.randomUUID().

6. Memory Leak Potential (Low)

Location: AutomatedSimulationPage.tsx:129

Async generator not cleaned up on unmount. Implement AbortController.

7. Other Minor Issues

• Inconsistent null handling using .startswith("(") checks
• Missing URL validation before web search
• Documentation gaps (OpenAPI specs, user docs)
• Web search results unbounded (should limit like website content)

📋 Checklist for Merge

• Critical: Add comprehensive unit tests
• Critical: Add integration tests for new endpoints
• High: Fix API key management (use centralized config)
• High: Sanitize error messages
• Medium: Extract hardcoded model version
• Medium: Implement AbortController
• Low: Fix message ID collision potential
• Low: Add API documentation

🎯 Overall Assessment

Quality: 7/10 | Security: 7/10 | Completeness: 6/10

Main concerns:

1. Missing test coverage (blocks merge per CLAUDE.md)
2. API key management needs hardening
3. Error handling could leak internal details

Once tests are added and high-priority security issues are addressed, this will be ready to merge.

Great work overall! The web search integration is innovative and the streaming UX is polished.

Estimated effort: 4-6 hours (3-4h tests, 1h security, 1h docs)