farentsen
715a6ca370
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.
285 lines
11 KiB
YAML
285 lines
11 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: BenefitsAgent Tools
|
|
version: 1.1.0
|
|
description: Tools for AskBenefits — a healthcare plan member assistant.
|
|
servers:
|
|
- url: https://taller-wox.fitlabs.dev/api
|
|
|
|
paths:
|
|
|
|
/historical-procedures:
|
|
post:
|
|
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: List of matching procedure records
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ResultArray'
|
|
|
|
/available-procedures:
|
|
post:
|
|
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: List of matching available-procedure records
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ResultArray'
|
|
|
|
/member-insights:
|
|
get:
|
|
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, plan data, and overdue procedures
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/MemberInsightsResponse'
|
|
|
|
/schedule:
|
|
get:
|
|
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: Scheduling guidance text
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ScheduleResponse'
|
|
|
|
components:
|
|
schemas:
|
|
ProcedureQuery:
|
|
type: object
|
|
required: [filters, group_by]
|
|
properties:
|
|
filters:
|
|
type: string
|
|
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 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
|