farentsen/taller-wox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(api): tolerate column aliases (procedure_name → procedure) + Spanish value mappings

Browse Source 
El LLM de watsonx Orchestrate estaba alucinando nombres de columnas
(procedure_name en lugar de procedure) y los valores de procedimientos
en español sin traducir. Dos fixes:

1. Backend (benefits_api.py): mapas _COLUMN_ALIASES y _VALUE_ALIASES
   resuelven aliases comunes (procedure_name, name, plan, etc.) y
   traducciones ES→EN (radiografía → X Ray, resonancia → MRI, etc.)
   antes de aplicar el filtro. Mensajes de error ahora listan columnas
   válidas para que el agente se corrija solo.

2. OpenAPI spec (yaml + json): description de cada operación ahora
   enumera explícitamente las columnas válidas y los valores válidos
   del campo procedure, más una sección VALUE MAPPING ES→EN para que
   el LLM no tenga que adivinar.
This commit is contained in:
farentsen
2026-05-13 14:51:31 +00:00
parent 1f2ad8d235
commit 715a6ca370
3 changed files with 501 additions and 353 deletions
Download Patch File Download Diff File Expand all files Collapse all files

531
material/openapi-tools-spec.yaml
View File

@@ -1,355 +1,284 @@
openapi: 3.0.3
info:
title: BenefitsAgent Tools
version: 1.0.0
version: 1.1.0
description: Tools for AskBenefits — a healthcare plan member assistant.
servers:
- url: https://taller-wox.fitlabs.dev/api
description: Local development server
- url: https://taller-wox.fitlabs.dev/api
paths:
/historical-procedures:
post:
summary: This tool enables intelligent analysis and summarization of the historical
procedures dataset.
description: |-
This tool enables intelligent analysis and summarization of the historical procedures dataset.
### Key Features
- Filtering on any combination of columns
- Grouping and aggregation of results
### Dataset Overview
Detected columns:
- **member_name**: e.g., Alice, Bob, Charlie...
- **relationship**: e.g., Mother, Father, Son...
- **age**: e.g., 42, 45, 12...
- **gender**: e.g., Female, Male
- **procedure**: e.g., Annual Physical Exam, Appendectomy, CT Scan...
- **procedure_type**: e.g., preventive, surgery, diagnostic...
- **location**: e.g., City Hospital, Green Valley Clinic, Sunrise Health...
- **date**: e.g., 2024-04-28, 2023-05-02, 2022-05-11...
- **in_network**: e.g., True, False
- **member_plan**: e.g., Gold PPO, Family Plan - Silver EPO
- **accepted_plans**: e.g., Gold PPO, Family Plan - Silver EPO, Medicare Advantage, Gold PPO, Family Plan - Silver EPO, Family Plan - Silver EPO, Medicare Advantage...
- **cost_facility**: e.g., 29.4, 48.02, 30.8...
- **cost_physician**: e.g., 199.09, 189.75, 128.9...
- **cost_anesthesia**: e.g., 0.0, 2024.21, 2257.4...
- **cost_medication**: e.g., 4.19, 5.53, 7.15...
- **total_cost**: e.g., 232.68, 243.3, 166.85...
- **facility_rating**: e.g., 4.7, 4.5, 4.6...
- **notes**: e.g., Annual Physical Exam performed at City Hospital., Appendectomy performed at City Hospital., CT Scan performed at Green Valley Clinic....
### Example Input:
```json
{
"filters": [
{
"column": "member_name",
"operator": "equals",
"value": "Alice"
}
]
}
{
"filters": [
{
"column": "member_name",
"operator": "contains",
"value": "Ali"
}
]
}
{
"filters": [
{
"column": "member_name",
"operator": "ne",
"value": "Alice"
}
]
}
{
"filters": [
{
"column": "age",
"operator": "gt",
"value": 22.69
}
]
}
{
"filters": [
{
"column": "age",
"operator": "lt",
"value": 27.73
}
]
}
{
"filters": [
{
"column": "age",
"operator": "ge",
"value": 25
}
]
}
{
"filters": [
{
"column": "age",
"operator": "le",
"value": 25
}
]
}
{
"filters": [
{
"column": "age",
"operator": "ne",
"value": 25
}
]
}
{
"group_by": [
"member_name",
"relationship"
]
}
{
"filters": [
{
"column": "member_name",
"operator": "equals",
"value": "Alice"
},
{
"column": "age",
"operator": "ge",
"value": 12.0
}
],
"group_by": [
"relationship"
]
}
```
Example Questions:
- "What rows match member_name = Alice?" → `{"filters": [{"column": "member_name", "operator": "equals", "value": "Alice"}]}`
- "What rows do not match member_name = Alice?" → `{"filters": [{"column": "member_name", "operator": "ne", "value": "Alice"}]}`
- "What rows contain 'Ali' in member_name?" → `{"filters": [{"column": "member_name", "operator": "contains", "value": "Ali"}]}`
- "What rows have age greater than 25.21?" → `{"filters": [{"column": "age", "operator": "gt", "value": 25.21}]}`
- "What rows have age less than 25.21?" → `{"filters": [{"column": "age", "operator": "lt", "value": 25.21}]}`
- "What rows have age greater than or equal to 25.21?" → `{"filters": [{"column": "age", "operator": "ge", "value": 25.21}]}`
- "What rows have age less than or equal to 25.21?" → `{"filters": [{"column": "age", "operator": "le", "value": 25.21}]}`
- "What rows do not have age equal to 25.21?" → `{"filters": [{"column": "age", "operator": "ne", "value": 25.21}]}`
- "What is the average of age grouped by member_name?" → `{"group_by": ["member_name"]}`
- "What is the total age for member_name = 25.210526315789473 grouped by relationship?" → `{"filters": [{"column": "member_name", "operator": "equals", "value": "25.210526315789473"}], "group_by": ["relationship"]}`
operationId: query_historical_procedures
summary: Query the member's past medical procedures
description: |
Retrieves the member's historical medical procedures with optional
filtering and aggregation. Use this tool when the user asks about
past procedures, what they paid for previous treatments, or wants
a summary of their medical history.
Example questions this tool answers:
- "What procedures have I had this year?"
- "How much did I pay for my last X-ray?"
- "Show me all procedures at City Hospital."
- "What did I spend on diagnostic procedures?"
VALID COLUMN NAMES for filters and group_by:
- member_name (string)
- relationship (string: Self, Spouse, Mother, Father, Son, Daughter)
- age (integer)
- gender (string: Female, Male)
- procedure (string: "Annual Physical Exam", "MRI", "CT Scan", "X Ray",
"Dental Cleaning", "Vision Exam", "Blood Test", "Appendectomy")
- procedure_type (string: preventive, surgery, diagnostic)
- location (string: City Hospital, Green Valley Clinic, Sunrise Health,
Regional Medical Center)
- date (string: YYYY-MM-DD)
- in_network (boolean: true, false)
- member_plan (string: Gold PPO, Family Plan - Silver EPO, Bronze HDHP)
- accepted_plans (string)
- cost_facility, cost_physician, cost_anesthesia, cost_medication,
total_cost (number)
- facility_rating (number)
- notes (string)
IMPORTANT: Use exactly these column names. Do NOT use "procedure_name",
"name", or other variants. Both filters and group_by must be passed
as JSON-encoded strings (not arrays).
Supported operators: equals, ne, contains, gt, lt, ge, le.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcedureQuery'
examples:
filter_xray:
summary: Find the member's X-Ray history
value:
filters: '[{"column":"procedure","operator":"equals","value":"X Ray"}]'
group_by: '[]'
filter_by_member:
summary: Filter rows by member name
value:
filters: '[{"column":"member_name","operator":"equals","value":"Charlie Smith"}]'
group_by: '[]'
filter_contains:
summary: Filter by partial match
value:
filters: '[{"column":"procedure","operator":"contains","value":"MRI"}]'
group_by: '[]'
group_by_relationship:
summary: Aggregate costs by family relationship
value:
filters: '[]'
group_by: '["relationship"]'
responses:
'200':
description: Successful result
description: List of matching procedure records
content:
application/json:
schema:
type: object
properties:
result:
type: object
$ref: '#/components/schemas/ResultArray'
/available-procedures:
post:
summary: This tool enables intelligent analysis and summarization of the available
procedures dataset.
description: |-
This tool enables intelligent analysis and summarization of the available procedures dataset.
### Key Features
- Filtering on any combination of columns
- Grouping and aggregation of results
### Dataset Overview
Detected columns:
- **procedure**: e.g., Angioplasty, Annual Physical Exam, Appendectomy...
- **location**: e.g., City Hospital, Regional Medical Center, Green Valley Clinic...
- **facility_rating**: e.g., 4.7, 4.3, 4.5...
- **distance_miles**: e.g., 5.2, 12.6, 1.2...
- **gold_ppo_plan_accepted**: e.g., True, False
- **silver_epo_plan_accepted**: e.g., True
- **accepted_plans**: e.g., Gold PPO, Family Plan - Silver EPO, Medicare Advantage, Family Plan - Silver EPO, Bronze HDHP, Medicaid, Gold PPO, Family Plan - Silver EPO...
- **cost_facility**: e.g., 9432.8, 23594.95, 3807.32...
- **cost_physician**: e.g., 4774.57, 4897.27, 5687.8...
- **cost_anesthesia**: e.g., 1894.37, 581.04, 293.41...
- **cost_medication**: e.g., 834.8, 783.86, 1301.58...
- **total_cost**: e.g., 16936.54, 29857.12, 11090.11...
### Example Input:
```json
{
"filters": [
{
"column": "procedure",
"operator": "equals",
"value": "Angioplasty"
}
]
}
{
"filters": [
{
"column": "procedure",
"operator": "contains",
"value": "Ang"
}
]
}
{
"filters": [
{
"column": "procedure",
"operator": "ne",
"value": "Angioplasty"
}
]
}
{
"filters": [
{
"column": "facility_rating",
"operator": "gt",
"value": 4.01
}
]
}
{
"filters": [
{
"column": "facility_rating",
"operator": "lt",
"value": 4.9
}
]
}
{
"filters": [
{
"column": "facility_rating",
"operator": "ge",
"value": 4
}
]
}
{
"filters": [
{
"column": "facility_rating",
"operator": "le",
"value": 4
}
]
}
{
"filters": [
{
"column": "facility_rating",
"operator": "ne",
"value": 4
}
]
}
{
"group_by": [
"procedure",
"location"
]
}
{
"filters": [
{
"column": "procedure",
"operator": "equals",
"value": "Angioplasty"
},
{
"column": "facility_rating",
"operator": "ge",
"value": 4.5
}
],
"group_by": [
"location"
]
}
```
Example Questions:
- "What rows match procedure = Angioplasty?" → `{"filters": [{"column": "procedure", "operator": "equals", "value": "Angioplasty"}]}`
- "What rows do not match procedure = Angioplasty?" → `{"filters": [{"column": "procedure", "operator": "ne", "value": "Angioplasty"}]}`
- "What rows contain 'Ang' in procedure?" → `{"filters": [{"column": "procedure", "operator": "contains", "value": "Ang"}]}`
- "What rows have facility_rating greater than 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "gt", "value": 4.45}]}`
- "What rows have facility_rating less than 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "lt", "value": 4.45}]}`
- "What rows have facility_rating greater than or equal to 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "ge", "value": 4.45}]}`
- "What rows have facility_rating less than or equal to 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "le", "value": 4.45}]}`
- "What rows do not have facility_rating equal to 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "ne", "value": 4.45}]}`
- "What is the average of facility_rating grouped by procedure?" → `{"group_by": ["procedure"]}`
- "What is the total facility_rating for procedure = 4.450442477876106 grouped by location?" → `{"filters": [{"column": "procedure", "operator": "equals", "value": "4.450442477876106"}], "group_by": ["location"]}`
operationId: query_available_procedures
summary: Query available procedures and costs by provider
description: |
Searches the catalog of medical procedures available at in-network
and out-of-network providers, with cost, location, distance and
plan acceptance. Use this tool when the user asks where to get a
procedure, how much it costs, or wants to compare providers.
Example questions this tool answers:
- "How much does an MRI cost?"
- "Where can I get a dental cleaning near me?"
- "Which hospital has the cheapest CT scan?"
- "Is X-ray covered by my Gold PPO plan?"
VALID COLUMN NAMES for filters and group_by:
- procedure (string: "MRI", "CT Scan", "X Ray", "Annual Physical Exam",
"Appendectomy", "Dental Cleaning", "Vision Exam", "Blood Test",
"Angioplasty", "Ultrasound")
- location (string: City Hospital, Green Valley Clinic, Sunrise Health,
Regional Medical Center)
- facility_rating (number)
- distance_miles (number)
- gold_ppo_plan_accepted (boolean)
- silver_epo_plan_accepted (boolean)
- accepted_plans (string)
- cost_facility, cost_physician, cost_anesthesia, cost_medication,
total_cost (number)
IMPORTANT: Use exactly these column names. Do NOT use "procedure_name",
"name", or other variants. Both filters and group_by must be passed
as JSON-encoded strings (not arrays).
Supported operators: equals, ne, contains, gt, lt, ge, le.
VALUE MAPPING — when the user asks in Spanish, translate to the exact
English value the dataset uses BEFORE calling the tool:
- radiografía / rayos X → "X Ray"
- resonancia / resonancia magnética → "MRI"
- tomografía → "CT Scan"
- limpieza dental → "Dental Cleaning"
- examen visual / de la vista → "Vision Exam"
- examen anual / chequeo anual → "Annual Physical Exam"
- apendicectomía → "Appendectomy"
- análisis de sangre → "Blood Test"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcedureQuery'
examples:
filter_xray:
summary: Find X-Ray providers (use "X Ray" not "radiografia")
value:
filters: '[{"column":"procedure","operator":"equals","value":"X Ray"}]'
group_by: '[]'
filter_by_procedure:
summary: Find all MRI options
value:
filters: '[{"column":"procedure","operator":"equals","value":"MRI"}]'
group_by: '[]'
filter_cheap:
summary: Find procedures under $500
value:
filters: '[{"column":"total_cost","operator":"lt","value":500}]'
group_by: '[]'
group_avg_cost:
summary: Average cost by procedure
value:
filters: '[]'
group_by: '["procedure"]'
responses:
'200':
description: Successful result
description: List of matching available-procedure records
content:
application/json:
schema:
type: object
properties:
result:
type: object
$ref: '#/components/schemas/ResultArray'
/member-insights:
get:
summary: Returns member data including plan information and overdue procedures.
description: |-
Returns member data including:
- Plan information (medical, pharmacy, mental health, wellness, tax documents)
- Overdue preventive procedures
operationId: get_member_insights
summary: Get the member's plan profile and overdue procedures
description: |
Returns the member's full plan profile including medical plan
(deductible, copays, coinsurance), pharmacy plan, mental health
coverage, wellness benefits, tax documents, and a list of
preventive procedures the member is overdue for.
Use this tool when the user asks about their plan details,
deductible status, what their plan covers, or whether they are
overdue on any preventive checkups.
Example questions this tool answers:
- "What's my plan?"
- "How much have I met of my deductible?"
- "Am I overdue on any checkups?"
- "What's my copay for a specialist visit?"
responses:
'200':
description: Member profile and plan data
description: Member profile, plan data, and overdue procedures
content:
application/json:
schema:
type: object
properties:
result:
type: object
$ref: '#/components/schemas/MemberInsightsResponse'
/schedule:
get:
summary: Provides appointment scheduling guidance.
description: Provides appointment scheduling guidelines to help users arrange
medical visits through a live scheduling system.
operationId: get_scheduling_guidance
summary: Get instructions for scheduling a medical appointment
description: |
Returns step-by-step guidance for scheduling a medical appointment,
including which provider to call, what information to confirm, and
how to handle pre-authorizations.
Use this tool when the user asks to book, schedule, or arrange a
medical appointment.
Example questions this tool answers:
- "Schedule me an appointment."
- "How do I book a visit with a specialist?"
- "Can you set up my MRI?"
responses:
'200':
description: Synthetic appointment instructions
description: Scheduling guidance text
content:
application/json:
schema:
type: object
properties:
result:
type: string
$ref: '#/components/schemas/ScheduleResponse'
components:
schemas:
ProcedureQuery:
type: object
required: [filters, group_by]
properties:
filters:
type: string
description: JSON-encoded list of filter objects
example: '[{"column": "procedure", "operator": "equals", "value": "X ray"}]'
description: |
JSON-encoded array of filter objects. Each filter has shape
{"column": "<name>", "operator": "<op>", "value": <value>}.
Operators: equals, ne, contains, gt, lt, ge, le.
Pass "[]" (empty string-encoded array) for no filters.
example: '[{"column":"member_name","operator":"equals","value":"Charlie Smith"}]'
group_by:
type: string
description: JSON-encoded list of columns to group by
example: '["facility_rating"]'
description: |
JSON-encoded array of column names to aggregate by. Numeric
columns are averaged. Pass "[]" for no grouping.
example: '["relationship"]'
ResultArray:
type: object
properties:
result:
type: array
items:
type: object
additionalProperties: true
MemberInsightsResponse:
type: object
properties:
result:
type: object
properties:
member:
type: object
properties:
name: { type: string }
date_of_birth: { type: string }
plan: { type: string }
member_id: { type: string }
medical_plan:
type: object
pharmacy_plan:
type: object
mental_health:
type: object
wellness:
type: object
tax_documents:
type: object
overdue_procedures:
type: array
items:
type: object
properties:
procedure: { type: string }
last_date: { type: string }
recommended_frequency_months: { type: integer }
due_since_months: { type: integer }
priority: { type: string }
ScheduleResponse:
type: object
properties:
result:
type: string