Optimization And AI

Evidence-first optimization payloads, deterministic action previews, legacy chat, and module copilot surfaces.

Owner: AI optimization backend

Source Modules

• scripts/serve_client_portal.py
• LeafEnterprise/module_copilot.py
• LeafEnterprise/pocket_consultant.py
• LeafEnterprise/ai/

Endpoint Summary

Method	Path	Summary	Auth	Handler
POST	/api/actions/execute	Legacy optimization action execution endpoint.	trusted frontend proxy	_handle_execute_action
GET	/api/ai/runtime	Reports AI provider runtime, transport, and fallback posture.	trusted frontend proxy	_handle_ai_runtime
POST	/api/chat	Legacy guarded chat endpoint.	trusted frontend proxy	_handle_chat
POST	/api/module-actions/execute	Previews or executes deterministic module actions.	trusted frontend proxy	_handle_module_action_execute
POST	/api/module-copilot	Runs the governed module assistant for savings, AI optimization, pricing, contracts, or renewals.	trusted frontend proxy	_handle_module_copilot
POST	/api/optimization-report-pdf	Exports a print-first optimization PDF from the selected recommendation context.	trusted frontend proxy	_handle_optimization_report_pdf
GET	/api/optimize	Returns evidence-first optimization recommendations for the active report context.	trusted frontend proxy	_handle_optimize

Endpoint Details

POST /api/actions/execute

Legacy optimization action execution endpoint.

Property	Value
Handler	_handle_execute_action
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 409, 500

Query parameters: none

Body fields: action_id, mode, overrides, scope

Response sections: status, projected_savings, guardrails, trace_id

Tests / smoke paths: tests/test_pocket_consultant.py

Notes: Keep deterministic and guardrail-evaluated.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/actions/execute
• Route family: optimization-ai
• Source handler: _handle_execute_action
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/ai/runtime

Reports AI provider runtime, transport, and fallback posture.

Property	Value
Handler	_handle_ai_runtime
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 500

Query parameters: none

Body fields: none

Response sections: provider, transport, deployments, fallback

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Do not expose provider secrets.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/ai/runtime
• Route family: optimization-ai
• Source handler: _handle_ai_runtime
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/chat

Legacy guarded chat endpoint.

Property	Value
Handler	_handle_chat
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 429, 500

Query parameters: none

Body fields: question, messages, scope

Response sections: answer, grounding, guardrails, trace_id

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Legacy for Savings Audit and AI Optimization pages; use module-copilot for those modules.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/chat
• Route family: optimization-ai
• Source handler: _handle_chat
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/module-actions/execute

Previews or executes deterministic module actions.

Property	Value
Handler	_handle_module_action_execute
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 409, 500

Query parameters: none

Body fields: module_key, action_type, mode, scope, parameters, report_context

Response sections: status, preview, queue_request, guardrails, trace_id

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Executable actions must remain deterministic and queue/lineage-backed.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/module-actions/execute
• Route family: optimization-ai
• Source handler: _handle_module_action_execute
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/module-copilot

Runs the governed module assistant for savings, AI optimization, pricing, contracts, or renewals.

Property	Value
Handler	_handle_module_copilot
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 429, 500

Query parameters: none

Body fields: module_key, question, messages, scope, report_context

Response sections: answer, runtime, grounding, actions, trace_id

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Savings and AI Optimization use module_copilot, not legacy chat, for page AI.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/module-copilot
• Route family: optimization-ai
• Source handler: _handle_module_copilot
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/optimization-report-pdf

Exports a print-first optimization PDF from the selected recommendation context.

Property	Value
Handler	_handle_optimization_report_pdf
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 409, 500

Query parameters: none

Body fields: scope, action_id, overrides, report_context

Response sections: application/pdf

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Server-rendered export; not a screenshot of the browser chart state.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/optimization-report-pdf
• Route family: optimization-ai
• Source handler: _handle_optimization_report_pdf
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/optimize

Returns evidence-first optimization recommendations for the active report context.

Property	Value
Handler	_handle_optimize
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 404, 409, 500

Query parameters: pbm, tpa, group_name, start_date, end_date, request_number

Body fields: none

Response sections: recommendations, optimization_grounding, ai_parity, itr_handoff, contract_guarantee_evidence

Tests / smoke paths: tests/test_pocket_consultant.py, scripts/smoke_client_portal.py

Notes: Must expose missing evidence and block rebate-backed claims without exact evidence.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/optimize
• Route family: optimization-ai
• Source handler: _handle_optimize
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.