# Tale Agent — AI Features (Developer Guide)

This document describes the AI Conversational Survey Assistant capabilities built with Spring Boot 3 and Azure OpenAI via Spring AI. It covers endpoints, request/response contracts, configuration, security, limits, testing, and Azure deployment notes.

## Overview
- Purpose: Assist COMPANY_USER in designing high‑quality surveys conversationally.
- Backend: Spring Boot 3.x, Spring AI, Azure OpenAI (gpt‑4o configurable), Apache Tika for document parsing.
- Persistence: Drafts are never auto‑saved. Persist only via POST /api/surveys/ai/save.
- UI: Embedded tester at /ai-tester (Bootstrap 5, dark theme). Left pane = chat, right pane = live survey preview.

## Quickstart (Local)
1) Start app (profile dev). Navigate to http://localhost:8080/ai-tester
2) Paste a valid Bearer token (COMPANY_USER) into the Authorization field.
3) Type a message, toggle Stream on if desired, then Send to Chat or Generate Draft.
4) Watch token usage update. Use Save Survey to persist the current draft.
5) Use Reset to clear UI, or Reset Session to clear server-side memory for your user.

## Endpoints (base: /api/surveys/ai)
All endpoints require role COMPANY_USER.

1) POST /chat (multipart/form-data)
   - parts:
     - messages: JSON array of { role: string, content: string }
     - files: optional file(s) (pdf, docx, doc, txt, html)
   - returns: text/plain assistant reply

2) POST /chat/with-stats (multipart/form-data)
   - parts: same as /chat
   - returns: application/json { reply: string, tokens: { promptTokensApprox, completionTokensApprox, total } }

3) POST /chat/stream (multipart/form-data)
   - parts: same as /chat
   - returns: text/plain streamed response. Chunks are plain text. The final chunk begins with "##META##" and contains a JSON object with token usage:
     - example tail: "\n\n##META##{"promptTokensApprox":123,"completionTokensApprox":456,"total":579}"
   - The tester UI progressively renders chunks and parses the trailing META for tokens.

4) POST /draft (multipart/form-data)
   - parts: same as /chat
   - returns: SurveyDto JSON draft (not persisted)

5) POST /draft/with-stats (multipart/form-data)
   - parts: same as /draft
   - returns: application/json { draft: SurveyDto, tokens: { promptTokensApprox, completionTokensApprox, total } }

6) POST /save (application/json)
   - body: SurveyDto
   - returns: persisted SurveyDto

7) POST /session/reset
   - clears per-user in-memory history and last draft

Notes:
- The messages part must use Content-Type: application/json. In Postman, add a Pre-request Script to set contentType for the messages form-data field.

## Conversation + Agent
- Lightweight in-memory per-user history (last 20 turns) for context.
- Token usage estimation is returned on stats endpoints and via stream META frame.
- Agent-style directives supported in draft generation:
  - action: none | validate_draft | suggest_followups | request_save
  - Server executes validate/merge logic; save is only by calling /save.

## Tester UI (/ai-tester)
- Tech: Bootstrap 5, responsive dark theme.
- Features:
  - Split view: chat (left), live survey preview + JSON (right)
  - File upload: multiple files sent with each request
  - Streaming toggle: on for /chat/stream, off for /chat/with-stats
  - Auto-scroll chat during streams
  - Token badges (prompt/completion/total)
  - Reset (UI only) and Reset Session (server memory)
  - Prettify JSON, Save Survey
- Accessibility: Labels associated to inputs, aria-live on token info, adequate contrast; verify with real content.

## File Handling (Apache Tika)
- Max file size: 10 MB per file
- Max chars per file: ~200k
- Max combined chars: ~300k across all files
- Allowed content types (prefix-match):
  - application/pdf
  - application/vnd.openxmlformats-officedocument*
  - application/msword
  - text/plain
  - text/html
- Files outside limits are skipped with warnings; parsing errors are logged and ignored.

## Configuration
Set in src/main/resources/application.properties (or via environment/App Settings in Azure):
- spring.ai.azure.openai.endpoint
- spring.ai.azure.openai.api-key
- spring.ai.azure.openai.chat.options.deployment-name
- spring.servlet.multipart.max-file-size
- spring.servlet.multipart.max-request-size

Model options (defaults in code):
- temperature: 0.2
- maxTokens: 800 (chat), 1800 (draft), 1200 (followups)

## Security
- WebSecurityConfig and DevWebSecurityConfig whitelist /ai-tester/** static assets.
- All /api/surveys/ai/** endpoints require COMPANY_USER.

## Deployment notes (Azure)
- Configure App Settings for Spring AI Azure OpenAI values above.
- Ensure request body size limits accommodate documents.
- Enable Application Insights for telemetry (recommended).
- If using front door/proxy, allow streaming responses (disable response buffering for /api/surveys/ai/chat/stream).