ifixkart-backend/app/api/v1/routers/SimulationRouter.py

331 lines
12 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

"""
@router SimulationRouter (Backend/app/api/v1/routers/SimulationRouter.py)
@purpose REST API endpoints for Swarm Intelligence & Predictive Digital Twin simulations.
"""
import asyncio
from datetime import datetime
from typing import List, Optional, Dict, Any
from fastapi import APIRouter, Depends, HTTPException, Query, status, Request
from pydantic import BaseModel, Field
from sqlalchemy.orm import Session
from sqlalchemy import desc
from app.core.database.db_session import get_db
from app.core.permissions.RoleChecker import RoleChecker, get_current_user
from app.core.limiter import limiter
from app.models.UserModel import User
# Swarm Package Imports
from swarm.models.simulation_job import SimulationJob
from swarm.scenarios import SCENARIO_REGISTRY
from swarm.queue import execute_simulation_job, request_job_cancellation
from swarm.providers import get_llm_provider
from swarm.config import swarm_settings
router = APIRouter(
prefix="/api/v1/simulation",
tags=["Swarm Intelligence & Predictive Simulation"],
dependencies=[Depends(RoleChecker(["Super Admin", "Admin", "Store Manager", "Manager"]))]
)
# --- SCHEMAS ---
class ScenarioRunRequest(BaseModel):
scenario_type: str = Field(..., description="One of: pricing_elasticity, whatsapp_preflight, workshop_surge, fleet_quote")
input_params: Dict[str, Any] = Field(default_factory=dict)
store_id: int = Field(default=1)
class JobSummaryResponse(BaseModel):
job_id: str
scenario_type: str
status: str
store_id: int
created_at: datetime
execution_time_ms: Optional[int] = None
total_cost_usd: Optional[float] = None
class JobDetailResponse(BaseModel):
id: str
store_id: int
user_id: int
scenario_type: str
status: str
input_params: Dict[str, Any]
historical_baseline: Optional[Dict[str, Any]] = None
simulation_dispersion: Optional[Dict[str, Any]] = None
calibrated_projection: Optional[Dict[str, Any]] = None
summary_metrics: Optional[Dict[str, Any]] = None
report_markdown: Optional[str] = None
agent_logs: Optional[List[Dict[str, Any]]] = None
error_message: Optional[str] = None
execution_time_ms: Optional[int] = None
prompt_tokens: Optional[int] = None
completion_tokens: Optional[int] = None
total_cost_usd: Optional[float] = None
last_heartbeat_at: Optional[datetime] = None
created_at: datetime
started_at: Optional[datetime] = None
completed_at: Optional[datetime] = None
class PersonaInterviewRequest(BaseModel):
agent_id: str
question: str
class PersonaInterviewResponse(BaseModel):
agent_id: str
question: str
response: str
latency_ms: int
# --- ENDPOINTS ---
@router.get("/scenarios")
def list_available_scenarios():
"""Lists all registered simulation scenarios and sample parameters."""
scenarios_meta = {
"pricing_elasticity": {
"title": "Dynamic Pricing & Discount Elasticity Predictor",
"description": "Simulates customer price sensitivity, sales volume change, and margin cannibalization.",
"default_params": {
"discount_pct": 15.0,
"current_price": 3500.0,
"cost_price": 2100.0,
"target_category": "Display & Touch Screens"
}
},
"whatsapp_preflight": {
"title": "WhatsApp Campaign Pre-Flight & Deliverability Risk",
"description": "Simulates customer reception, click-through rates, and phone number block/spam hazard.",
"default_params": {
"message_template": "Exclusive 20% off all display repairs this weekend at iFixKart!",
"offer_type": "20% Discount",
"frequency_per_month": 2,
"target_segment": "Past Customers"
}
},
"workshop_surge": {
"title": "Workshop SLA & Repair Volume Surge",
"description": "Simulates repair ticket intake surges and parts lead-time delays to forecast bottlenecks.",
"default_params": {
"surge_multiplier": 1.5,
"parts_delay_days": 3,
"active_technicians": 4
}
},
"fleet_quote": {
"title": "B2B Corporate Fleet Quote Negotiation",
"description": "Simulates corporate procurement committee (CFO, IT Admin, Legal) deliberation.",
"default_params": {
"device_count": 50,
"quoted_price_per_unit": 4200.0,
"warranty_months": 6,
"turnaround_days": 3
}
}
}
return {
"available_scenarios": list(SCENARIO_REGISTRY.keys()),
"scenarios": scenarios_meta,
"max_concurrent_simulations": swarm_settings.MAX_CONCURRENT_SIMULATIONS,
"job_timeout_seconds": swarm_settings.JOB_TIMEOUT_SECONDS
}
@router.post("/scenarios/run", status_code=status.HTTP_202_ACCEPTED)
@limiter.limit("5/minute")
async def launch_simulation(
request: Request,
payload: ScenarioRunRequest,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""
Validates parameters, enforces concurrency bounds, enqueues the simulation job,
and returns HTTP 202 Accepted.
"""
if payload.scenario_type not in SCENARIO_REGISTRY:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=f"Invalid scenario '{payload.scenario_type}'. Supported: {list(SCENARIO_REGISTRY.keys())}"
)
# Check store active running jobs
active_count = (
db.query(SimulationJob)
.filter(
SimulationJob.store_id == payload.store_id,
SimulationJob.status.in_(["QUEUED", "CLAIMED", "RUNNING"])
)
.count()
)
if active_count >= swarm_settings.MAX_CONCURRENT_SIMULATIONS:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail=f"Store concurrency limit reached ({swarm_settings.MAX_CONCURRENT_SIMULATIONS} concurrent runs). Please wait for ongoing jobs to complete."
)
# Persist QUEUED state
import ulid
job_id = str(ulid.ULID())
job = SimulationJob(
id=job_id,
store_id=payload.store_id,
user_id=current_user.id if hasattr(current_user, "id") else 1,
scenario_type=payload.scenario_type,
status="QUEUED",
input_params=payload.input_params
)
db.add(job)
db.commit()
# Dispatch execution cleanly in background thread running independent event loop
import threading
threading.Thread(
target=lambda: asyncio.run(execute_simulation_job(job_id)),
daemon=True,
name=f"sim-worker-{job_id[:8]}"
).start()
return {
"message": "Simulation job enqueued successfully.",
"job_id": job_id,
"status": "QUEUED",
"poll_url": f"/api/v1/simulation/jobs/{job_id}"
}
@router.get("/jobs/{job_id}", response_model=JobDetailResponse)
def get_simulation_job_detail(
job_id: str,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""Retrieves complete details, status, and prediction report for a simulation job."""
job = db.query(SimulationJob).filter(SimulationJob.id == job_id).first()
if not job:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Simulation job '{job_id}' not found.")
return JobDetailResponse(
id=job.id,
store_id=job.store_id,
user_id=job.user_id,
scenario_type=job.scenario_type,
status=job.status,
input_params=job.input_params or {},
historical_baseline=job.historical_baseline,
simulation_dispersion=job.simulation_dispersion,
calibrated_projection=job.calibrated_projection,
summary_metrics=job.summary_metrics,
report_markdown=job.report_markdown,
agent_logs=job.agent_logs,
error_message=job.error_message,
execution_time_ms=job.execution_time_ms,
prompt_tokens=job.prompt_tokens,
completion_tokens=job.completion_tokens,
total_cost_usd=float(job.total_cost_usd) if job.total_cost_usd is not None else None,
last_heartbeat_at=job.last_heartbeat_at,
created_at=job.created_at,
started_at=job.started_at,
completed_at=job.completed_at
)
@router.get("/jobs", response_model=List[JobSummaryResponse])
def list_simulation_jobs(
store_id: int = Query(default=1),
skip: int = Query(default=0, ge=0),
limit: int = Query(default=20, ge=1, le=100),
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""Lists historical simulation runs for a store."""
jobs = (
db.query(SimulationJob)
.filter(SimulationJob.store_id == store_id)
.order_by(desc(SimulationJob.created_at))
.offset(skip)
.limit(limit)
.all()
)
return [
JobSummaryResponse(
job_id=j.id,
scenario_type=j.scenario_type,
status=j.status,
store_id=j.store_id,
created_at=j.created_at,
execution_time_ms=j.execution_time_ms,
total_cost_usd=float(j.total_cost_usd) if j.total_cost_usd is not None else None
)
for j in jobs
]
@router.post("/jobs/{job_id}/cancel")
def cancel_simulation_job(
job_id: str,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""Requests immediate cancellation of a running or queued simulation."""
job = db.query(SimulationJob).filter(SimulationJob.id == job_id).first()
if not job:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Simulation job '{job_id}' not found.")
if job.status in ["COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED"]:
return {"message": f"Job is already in final state '{job.status}'.", "status": job.status}
success = request_job_cancellation(job_id)
return {"message": "Cancellation requested successfully.", "job_id": job_id, "cancelled": success}
@router.post("/jobs/{job_id}/interview", response_model=PersonaInterviewResponse)
async def interview_simulated_persona(
job_id: str,
payload: PersonaInterviewRequest,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user)
):
"""
Directly asks questions to a simulated persona from a completed simulation run.
Uses multi-turn chat adhering to the persona's persona profile.
"""
job = db.query(SimulationJob).filter(SimulationJob.id == job_id).first()
if not job:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Simulation job '{job_id}' not found.")
if job.status != "COMPLETED":
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=f"Cannot interview persona: Job is in state '{job.status}'. Job must be 'COMPLETED'."
)
# Locate persona in agent logs
agent_logs = job.agent_logs or []
target_log = next((log for log in agent_logs if log.get("agent_id") == payload.agent_id), None)
if not target_log:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"Agent '{payload.agent_id}' was not part of simulation run '{job_id}'."
)
provider = get_llm_provider()
system_prompt = (
f"You are simulated customer '{payload.agent_id}' belonging to archetype '{target_log.get('archetype', 'Customer')}'. "
f"In a simulated scenario involving '{job.scenario_type}', your recorded decision was '{target_log.get('decision', 'N/A')}'. "
f"Answer the store manager's question in 1–2 authentic sentences strictly from your persona's perspective."
)
messages = [{"role": "user", "content": payload.question}]
reply, usage = await provider.chat(messages, system_prompt=system_prompt)
return PersonaInterviewResponse(
agent_id=payload.agent_id,
question=payload.question,
response=reply,
latency_ms=usage.latency_ms
)