Scoring & Feedback Generation

Step 5 is the final stage of the analysis pipeline, where all collected metrics are synthesized into a single numerical score (0-100) and comprehensive Markdown-formatted feedback with actionable recommendations.

Function Signature

def _paso5_generar_feedback(m: Dict, b: Dict, r: Dict) -> Tuple[float, str]:
    """
    Generates final score and feedback from metrics, benchmarking, and risk data.
    Returns (score, feedback_markdown).
    """

Input Parameters

The function receives dictionaries from the previous three steps:

m (metricas): Dexterity metrics from Step 2
b (benchmarking): Precision data from Step 3
r (riesgo): Risk analysis from Step 4

Scoring Algorithm

The score starts at 100 and penalties are subtracted:

analysis_pipeline.py

score = 100.0
score -= r["touches"] * 8
score -= r["hemorrhages"] * 15
if m["economia"] > 1.5: score -= 10
score = max(0, min(100, score))

Penalty Breakdown

Hemorrhages: -15 points each

Hemorrhages are the most critical errors. Each bleeding event costs 15 points.Rationale: In real surgery, vascular damage is life-threatening and must be avoided at all costs.

score -= r["hemorrhages"] * 15

Tumor Touches: -8 points each

Contact with tumor tissue is a moderate error. Each touch costs 8 points.Rationale: Tumor contact can spread cancer cells, but is less immediately dangerous than hemorrhage.

score -= r["touches"] * 8

Poor Economy: -10 points

If economy of movement exceeds 1.5x (path is 50% longer than necessary), a 10-point penalty applies.Rationale: Inefficient movements indicate poor planning and increase procedure time and tissue trauma.

if m["economia"] > 1.5: score -= 10

The final score is clamped between 0 and 100: score = max(0, min(100, score))

Performance Tiers

Based on the final score, performance is classified into one of four tiers:

status = ("🌟 EXCELENTE" if score >= 90 else 
          "✅ BUENO" if score >= 75 else 
          "⚠️ MEJORABLE" if score >= 60 else 
          "❌ DEFICIENTE")

🌟 EXCELENTE (90-100)
✅ BUENO (75-89)
⚠️ MEJORABLE (60-74)
❌ DEFICIENTE (<60)

Characteristics:

Zero or one minor error
Excellent economy of movement
High precision
Smooth, controlled technique

Message: “Outstanding surgical performance. Continue this level of excellence.”

Feedback Structure

The feedback is formatted as Markdown with four main sections:

feedback = f"""### {status} - Score: {score:.1f}/100

#### 🚨 ALERTAS CRÍTICAS
- Hemorragias: {r["hemorrhages"]} {"(REVISAR TÉCNICA)" if r["hemorrhages"] > 0 else "(Ninguna)"}
- Contactos Tumor: {r["touches"]}
- Cuadrantes de Riesgo: {", ".join(r["cuadrantes"]) if r["cuadrantes"] else "Ninguno"}

#### 📊 MÉTRICAS DE DESTREZA
- **Economía de Movimiento:** {m["economia"]:.2f}x (Ideal < 1.2x)
- **Fluidez (Jerk Promedio):** {m["j_avg"]:.2f} 
- **Precisión vs Patrón Oro:** {b["precision"]:.1f}%

#### 📈 ESTADÍSTICAS
- **Duración Total:** {m["duration"]:.1f}s
- **Distancia Recorrida:** {m["total_dist"]:.2f} unidades
- **Velocidad Promedio:** {m["v_avg"]:.2f} u/s

#### 💡 RECOMENDACIONES
"""

1. Critical Alerts (🚨)

Highlights the most severe issues that need immediate attention:

Hemorrhages: Number of bleeding events with urgent flag if > 0
Tumor Touches: Count of cancerous tissue contacts
Risk Quadrants: Spatial zones where errors occurred

2. Dexterity Metrics (📊)

Key performance indicators from the physics analysis:

Economy of Movement: Path efficiency ratio (ideal < 1.2x)
Fluidity (Average Jerk): Smoothness indicator
Precision vs Gold Standard: Percentage score for path accuracy

3. Statistics (📈)

Raw data about the procedure:

Total Duration: Time from start to finish
Distance Traveled: Total path length
Average Velocity: Mean movement speed

4. Recommendations (💡)

Conditional, personalized advice based on specific issues:

if r["hemorrhages"] > 0: 
    feedback += "- Priorizar control vascular en cuadrantes críticos.\n"
if m["economia"] > 1.8: 
    feedback += "- Planificar trayectorias más directas para reducir fatiga.\n"
if b["precision"] < 70: 
    feedback += "- Mantener mayor estabilidad en la ejecución del path ideal.\n"
if score < 80: 
    feedback += "- Incrementar práctica en simulador para mejorar coordinación motora.\n"

Recommendations are only added if specific conditions are met, making feedback highly personalized.

Complete Example Output

Input Metrics

{
  "metricas": {
    "economia": 1.35,
    "v_avg": 2.73,
    "a_max": 8.42,
    "j_avg": 0.67,
    "total_dist": 123.45,
    "duration": 45.3
  },
  "benchmarking": {
    "desviacion_avg": 2.35,
    "precision": 76.5
  },
  "riesgo": {
    "touches": 2,
    "hemorrhages": 1,
    "cuadrantes": ["Sup-Der"]
  }
}

Generated Output

score = 100 - (2 * 8) - (1 * 15) = 69.0
status = "⚠️ MEJORABLE"

### ⚠️ MEJORABLE - Score: 69.0/100

#### 🚨 ALERTAS CRÍTICAS
- Hemorragias: 1 (REVISAR TÉCNICA)
- Contactos Tumor: 2
- Cuadrantes de Riesgo: Sup-Der

#### 📊 MÉTRICAS DE DESTREZA
- **Economía de Movimiento:** 1.35x (Ideal < 1.2x)
- **Fluidez (Jerk Promedio):** 0.67
- **Precisión vs Patrón Oro:** 76.5%

#### 📈 ESTADÍSTICAS
- **Duración Total:** 45.3s
- **Distancia Recorrida:** 123.45 unidades
- **Velocidad Promedio:** 2.73 u/s

#### 💡 RECOMENDACIONES
- Priorizar control vascular en cuadrantes críticos.
- Mantener mayor estabilidad en la ejecución del path ideal.
- Incrementar práctica en simulador para mejorar coordinación motora.

Recommendation Logic

Hemorrhages > 0

“Priorizar control vascular en cuadrantes críticos.”

Economy > 1.8

“Planificar trayectorias más directas para reducir fatiga.”

Precision < 70%

“Mantener mayor estabilidad en la ejecución del path ideal.”

Score < 80

“Incrementar práctica en simulador para mejorar coordinación motora.”

Clinical Value

The feedback system provides:

Objective Scoring: Removes subjective bias from performance evaluation
Actionable Insights: Specific recommendations tied to measurable metrics
Progress Tracking: Consistent scoring enables longitudinal performance monitoring
Focused Training: Pinpoints exact areas needing improvement

Performance

Feedback generation is extremely fast:

String formatting: Simple concatenation and f-strings
Conditional logic: Basic if statements
No heavy computation: Just assembling pre-calculated metrics

Typical performance: Less than 1ms

Next Steps

Setup AI Environment

Install dependencies and configure the AI service

Use the AI Client

Learn how to integrate with the backend API

Overview

Components

Integration

Scoring & Feedback Generation

Function Signature

Input Parameters

Scoring Algorithm

Penalty Breakdown

Performance Tiers

Feedback Structure

1. Critical Alerts (🚨)

2. Dexterity Metrics (📊)

3. Statistics (📈)

4. Recommendations (💡)

Complete Example Output

Input Metrics

Generated Output

Recommendation Logic

Hemorrhages > 0

Economy > 1.8

Precision < 70%

Score < 80

Clinical Value

Performance

Next Steps

Setup AI Environment

Use the AI Client

Build docs developers (and LLMs) love

Overview

Components

Integration

​Function Signature

​Input Parameters

​Scoring Algorithm

​Penalty Breakdown

​Performance Tiers

​Feedback Structure

​1. Critical Alerts (🚨)

​2. Dexterity Metrics (📊)

​3. Statistics (📈)

​4. Recommendations (💡)

​Complete Example Output

​Input Metrics

​Generated Output

​Recommendation Logic

Hemorrhages > 0

Economy > 1.8

Precision < 70%

Score < 80

​Clinical Value

​Performance

​Next Steps

Setup AI Environment

Use the AI Client

Build docs developers (and LLMs) love

Function Signature

Input Parameters

Scoring Algorithm

Penalty Breakdown

Performance Tiers

Feedback Structure

1. Critical Alerts (🚨)

2. Dexterity Metrics (📊)

3. Statistics (📈)

4. Recommendations (💡)

Complete Example Output

Input Metrics

Generated Output

Recommendation Logic

Clinical Value

Performance

Next Steps