docs/AI_FEATURES_PHASES.md

AI feature phases (strict — no backend infra)

Backend scale (Redis job queue, distributed rate limits, Temporal, stale-job sweepers) is not an AI phase. See OPTIMIZATION_SUMMARY.md → Backend infrastructure.

Old doc label	Correct bucket
Phase 3 (Redis)	Backend — not AI
Phase 2 (Temporal)	Backend — not AI
SCALE_OPTIMIZATION_PROFILE	Backend + mixed — also toggles AI Phase 3 flags

GET /health exposes ai_phases (this document) separately from infrastructure (Redis, job queue).

---

Phase 1 — Core RAG generation

Purpose: Turn surveyor notes + tenant library into RICS section prose via retrieval-augmented generation.

Capability	Module / API	Requires OPENAI_API_KEY
Section generate / proofread / enhance	app/services/generation.py, POST …/generate	Yes
Notes expansion	app/generator/notes_expander.py	Yes
Writing style analysis	app/generator/style_analyzer.py	Yes
Main LLM adapt + verify pass	app/generator/adapter.py, postprocess.py	Yes
Embeddings + vector index	app/embeddings/, app/vectorstore/, app/ingest/	No (HF local default)
Retrieval + rerank + hierarchical RAG	app/retrieval/	No
Personalised tenant style RAG	app/services/personalised_rag.py	No (index); Yes (generate)
Upload sanitisation before index	app/services/document_sanitiser.py	Optional LLM; regex default
Interference levels (minimum / medium / maximum)	app/generator/prompts.py	Yes
Standard paragraphs injection	app/services/standard_paragraphs.py	No
Optional LLM section validator	LLM_SECTION_VALIDATOR_ENABLED	Yes

Default product path: NOTES_ONLY_GENERATION=true → standard pipeline on POST /generate (bullets are facts; uploads reference-only).

Key env (Phase 1):

OPENAI_API_KEY=…
CHAT_MODEL=gpt-4o-mini
PERSONALISED_STYLE_RAG_ENABLED=true
ENABLE_RAG_UPLOAD_SANITISATION=true
RAG_SANITISATION_USE_LLM=false
NOTES_ONLY_GENERATION=true

---

Phase 2 — Agentic inspector & multimodal

Purpose: OpenAI tool-calling inspector, full agentic report orchestration, and section photo vision.

Capability	Module / API	Gate
Inspector tool loop	app/agentic/inspector_loop.py, HeadAgent	INSPECTOR_TOOL_AGENT=true + API key
Multi-agent report (generate_full_report)	app/agentic/agents.py	Same
Agentic HTTP API	POST /reports/{id}/agentic/generate	Same
Inspector on main generate	POST /reports/{id}/generate	AGENTIC_INSPECTOR_WHEN_NOTES_ONLY=true or NOTES_ONLY_GENERATION=false
Section photo vision	app/services/photo_vision.py	SECTION_PHOTO_VISION_ENABLED=true + API key
Vision on upload (cache)	SECTION_PHOTO_ANALYZE_ON_UPLOAD	Same
LLM RAG sanitisation at ingest	RAG_SANITISATION_USE_LLM	Dev/staging; off on HF production_ai_profile

HF / production AI (recommended):

INSPECTOR_TOOL_AGENT=true
INSPECTOR_BODY_MODEL=gpt-4o-mini
AGENTIC_INSPECTOR_WHEN_NOTES_ONLY=true
SECTION_PHOTO_VISION_ENABLED=true
SECTION_PHOTO_VISION_MODEL=gpt-4o
PRIMARY_GENERATE_PIPELINE=agentic
PRODUCTION_AI_PROFILE=true

---

Phase 3 — AI latency & retrieval quality

Purpose: Same AI outputs, faster or cheaper — not separate workers or queues.

Capability	Env	Notes
Async OpenAI + parallel sections	ENABLE_ASYNC_PIPELINE=true	app/llm/async_llm_adapter.py, generation_facade.py
Speculative inspector tool prefetch	ENABLE_SPECULATIVE_EXECUTOR=true	Requires async + Phase 2 inspector path
OpenAI prompt cache keys	ENABLE_PROMPT_CACHING=true	Requires async
Global LLM concurrency cap	MAX_CONCURRENT_LLM_CALLS	Throttle / 429 retry
Hybrid BM25 + vector (RRF)	ENABLE_HYBRID_RETRIEVAL + VECTORSTORE_BACKEND=qdrant	Better retrieval
Semantic retrieval cache	SEMANTIC_CACHE_ENABLED + Qdrant	Caches embedding-neighbour hits
Qdrant vector backend	VECTORSTORE_BACKEND=qdrant	Re-ingest after switch

Not Phase 3 (backend): REDIS_URL, ENABLE_JOB_QUEUE, ENABLE_TEMPORAL_WORKFLOW, GENERATION_STALE_SWEEP_SECONDS, SCALE_OPTIMIZATION_PROFILE (mixed).

Example (local AI perf only):

ENABLE_ASYNC_PIPELINE=true
ENABLE_SPECULATIVE_EXECUTOR=true
ENABLE_PROMPT_CACHING=true
AGENTIC_INSPECTOR_WHEN_NOTES_ONLY=true
# Optional stronger retrieval:
# VECTORSTORE_BACKEND=qdrant
# QDRANT_URL=http://localhost:6333

---

Full-report time target (10 minutes)

Setting	Default	Role
GENERATION_SLA_SECONDS	600	Product target for batch / full-report jobs
GENERATION_TIMEOUT_SECONDS	720	Sweeper fails stuck jobs (SLA + 2 min grace)

Requirements to hit SLA (typical 15–25 sections):

1. AI Phase 3 on: ENABLE_ASYNC_PIPELINE=true and parallel multi-section (auto with PRODUCTION_AI_PROFILE or HF SPACE_ID).
2. Phase 2 on main path: AGENTIC_INSPECTOR_WHEN_NOTES_ONLY=true only if you need the inspector; standard pipeline is faster for bulk.
3. Interference: prefer medium or minimum for batch — maximum adds tokens and retries.
4. Bullets: empty sections stay blank; fill bullets per section before batch generate.
5. UI: batch poll waits at least 10 minutes before showing “still generating”.

Sequential generation (async off) often exceeds 10 minutes — not supported for full-report SLA.

---

Ship checklist by environment

Environment	Phase 1	Phase 2	Phase 3
HF Space pilot	API key + personalised RAG	Inspector + vision + AGENTIC_INSPECTOR_WHEN_NOTES_ONLY	Usually off (single process; async optional)
Docker single node	Same	Same	Optional async + speculation
Multi-replica AWS	Same	Same	Phase 3 AI + backend Redis queue (see PRODUCTION_REPORT.md)

---

Code map

Phase	Health JSON	Python
1–3	GET /health → ai_phases	app/optimization/ai_phases.py
Warnings	ai_phase_warnings	collect_ai_phase_warnings()
User-facing summary	ai_features	app/optimization/ai_readiness.py
Backend only	infrastructure	app/optimization/scale_status.py, Redis, jobs, Temporal