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.
279 lines
13 KiB
JSON
279 lines
13 KiB
JSON
{
|
|
"openapi": "3.0.3",
|
|
"info": {
|
|
"title": "BenefitsAgent Tools",
|
|
"version": "1.1.0",
|
|
"description": "Tools for AskBenefits \u2014 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\nfiltering and aggregation. Use this tool when the user asks about\npast procedures, what they paid for previous treatments, or wants\na summary of their medical history.\n\nExample questions this tool answers:\n- \"What procedures have I had this year?\"\n- \"How much did I pay for my last X-ray?\"\n- \"Show me all procedures at City Hospital.\"\n- \"What did I spend on diagnostic procedures?\"\n\nVALID COLUMN NAMES for filters and group_by:\n- member_name (string)\n- relationship (string: Self, Spouse, Mother, Father, Son, Daughter)\n- age (integer)\n- gender (string: Female, Male)\n- procedure (string: \"Annual Physical Exam\", \"MRI\", \"CT Scan\", \"X Ray\",\n \"Dental Cleaning\", \"Vision Exam\", \"Blood Test\", \"Appendectomy\")\n- procedure_type (string: preventive, surgery, diagnostic)\n- location (string: City Hospital, Green Valley Clinic, Sunrise Health,\n Regional Medical Center)\n- date (string: YYYY-MM-DD)\n- in_network (boolean: true, false)\n- member_plan (string: Gold PPO, Family Plan - Silver EPO, Bronze HDHP)\n- accepted_plans (string)\n- cost_facility, cost_physician, cost_anesthesia, cost_medication,\n total_cost (number)\n- facility_rating (number)\n- notes (string)\n\nIMPORTANT: Use exactly these column names. Do NOT use \"procedure_name\",\n\"name\", or other variants. Both filters and group_by must be passed\nas JSON-encoded strings (not arrays).\nSupported operators: equals, ne, contains, gt, lt, ge, le.\n",
|
|
"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\nand out-of-network providers, with cost, location, distance and\nplan acceptance. Use this tool when the user asks where to get a\nprocedure, how much it costs, or wants to compare providers.\n\nExample questions this tool answers:\n- \"How much does an MRI cost?\"\n- \"Where can I get a dental cleaning near me?\"\n- \"Which hospital has the cheapest CT scan?\"\n- \"Is X-ray covered by my Gold PPO plan?\"\n\nVALID COLUMN NAMES for filters and group_by:\n- procedure (string: \"MRI\", \"CT Scan\", \"X Ray\", \"Annual Physical Exam\",\n \"Appendectomy\", \"Dental Cleaning\", \"Vision Exam\", \"Blood Test\",\n \"Angioplasty\", \"Ultrasound\")\n- location (string: City Hospital, Green Valley Clinic, Sunrise Health,\n Regional Medical Center)\n- facility_rating (number)\n- distance_miles (number)\n- gold_ppo_plan_accepted (boolean)\n- silver_epo_plan_accepted (boolean)\n- accepted_plans (string)\n- cost_facility, cost_physician, cost_anesthesia, cost_medication,\n total_cost (number)\n\nIMPORTANT: Use exactly these column names. Do NOT use \"procedure_name\",\n\"name\", or other variants. Both filters and group_by must be passed\nas JSON-encoded strings (not arrays).\nSupported operators: equals, ne, contains, gt, lt, ge, le.\n\nVALUE MAPPING \u2014 when the user asks in Spanish, translate to the exact\nEnglish value the dataset uses BEFORE calling the tool:\n- radiograf\u00eda / rayos X \u2192 \"X Ray\"\n- resonancia / resonancia magn\u00e9tica \u2192 \"MRI\"\n- tomograf\u00eda \u2192 \"CT Scan\"\n- limpieza dental \u2192 \"Dental Cleaning\"\n- examen visual / de la vista \u2192 \"Vision Exam\"\n- examen anual / chequeo anual \u2192 \"Annual Physical Exam\"\n- apendicectom\u00eda \u2192 \"Appendectomy\"\n- an\u00e1lisis de sangre \u2192 \"Blood Test\"\n",
|
|
"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\n(deductible, copays, coinsurance), pharmacy plan, mental health\ncoverage, wellness benefits, tax documents, and a list of\npreventive procedures the member is overdue for.\n\nUse this tool when the user asks about their plan details,\ndeductible status, what their plan covers, or whether they are\noverdue on any preventive checkups.\n\nExample questions this tool answers:\n- \"What's my plan?\"\n- \"How much have I met of my deductible?\"\n- \"Am I overdue on any checkups?\"\n- \"What's my copay for a specialist visit?\"\n",
|
|
"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,\nincluding which provider to call, what information to confirm, and\nhow to handle pre-authorizations.\n\nUse this tool when the user asks to book, schedule, or arrange a\nmedical appointment.\n\nExample questions this tool answers:\n- \"Schedule me an appointment.\"\n- \"How do I book a visit with a specialist?\"\n- \"Can you set up my MRI?\"\n",
|
|
"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\n{\"column\": \"<name>\", \"operator\": \"<op>\", \"value\": <value>}.\nOperators: equals, ne, contains, gt, lt, ge, le.\nPass \"[]\" (empty string-encoded array) for no filters.\n",
|
|
"example": "[{\"column\":\"member_name\",\"operator\":\"equals\",\"value\":\"Charlie Smith\"}]"
|
|
},
|
|
"group_by": {
|
|
"type": "string",
|
|
"description": "JSON-encoded array of column names to aggregate by. Numeric\ncolumns are averaged. Pass \"[]\" for no grouping.\n",
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
} |