fix(api): tolerate column aliases (procedure_name → procedure) + Spanish value mappings
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:
@@ -2,41 +2,67 @@
|
||||
"openapi": "3.0.3",
|
||||
"info": {
|
||||
"title": "BenefitsAgent Tools",
|
||||
"version": "1.0.0"
|
||||
"version": "1.1.0",
|
||||
"description": "Tools for AskBenefits \u2014 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.\n### Key Features\n- Filtering on any combination of columns\n- Grouping and aggregation of results\n### Dataset Overview\nDetected columns:\n- **member_name**: e.g., Alice, Bob, Charlie...\n- **relationship**: e.g., Mother, Father, Son...\n- **age**: e.g., 42, 45, 12...\n- **gender**: e.g., Female, Male\n- **procedure**: e.g., Annual Physical Exam, Appendectomy, CT Scan...\n- **procedure_type**: e.g., preventive, surgery, diagnostic...\n- **location**: e.g., City Hospital, Green Valley Clinic, Sunrise Health...\n- **date**: e.g., 2024-04-28, 2023-05-02, 2022-05-11...\n- **in_network**: e.g., True, False\n- **member_plan**: e.g., Gold PPO, Family Plan - Silver EPO\n- **accepted_plans**: e.g., Gold PPO, Family Plan - Silver EPO, Medicare Advantage, Gold PPO, Family Plan - Silver EPO, Family Plan - Silver EPO, Medicare Advantage...\n- **cost_facility**: e.g., 29.4, 48.02, 30.8...\n- **cost_physician**: e.g., 199.09, 189.75, 128.9...\n- **cost_anesthesia**: e.g., 0.0, 2024.21, 2257.4...\n- **cost_medication**: e.g., 4.19, 5.53, 7.15...\n- **total_cost**: e.g., 232.68, 243.3, 166.85...\n- **facility_rating**: e.g., 4.7, 4.5, 4.6...\n- **notes**: e.g., Annual Physical Exam performed at City Hospital., Appendectomy performed at City Hospital., CT Scan performed at Green Valley Clinic....\n### Example Input:\n```json\n{\"filters\": [{\"column\": \"member_name\", \"operator\": \"equals\", \"value\": \"Alice\"}]}\n```\nExample Questions:\n- \"What rows match member_name = Alice?\" \u2192 `{\"filters\": [{\"column\": \"member_name\", \"operator\": \"equals\", \"value\": \"Alice\"}]}`",
|
||||
"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": "Successful result",
|
||||
"description": "List of matching procedure records",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"result": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
"$ref": "#/components/schemas/ResultArray"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -46,30 +72,56 @@
|
||||
},
|
||||
"/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.\n### Key Features\n- Filtering on any combination of columns\n- Grouping and aggregation of results\n### Dataset Overview\nDetected columns:\n- **procedure**: e.g., Angioplasty, Annual Physical Exam, Appendectomy...",
|
||||
"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": "Successful result",
|
||||
"description": "List of matching available-procedure records",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"result": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
"$ref": "#/components/schemas/ResultArray"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -79,20 +131,16 @@
|
||||
},
|
||||
"/member-insights": {
|
||||
"get": {
|
||||
"summary": "Returns member data including plan information and overdue procedures.",
|
||||
"description": "Returns member data including:\n- Plan information (medical, pharmacy, mental health, wellness, tax documents)\n- 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\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 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"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -102,20 +150,16 @@
|
||||
},
|
||||
"/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,\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": "Synthetic appointment instructions",
|
||||
"description": "Scheduling guidance text",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"result": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
"$ref": "#/components/schemas/ScheduleResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -128,19 +172,108 @@
|
||||
"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\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 list of columns to group by",
|
||||
"example": "[\"facility_rating\"]"
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user