taller-wox/material/openapi-tools-report.json

{
    "openapi": "3.0.3",
    "info": {
      "title": "Report API",
      "version": "2.0.0",
      "description": "Tools for generating HTML reports with WxO"
    },
    "servers": [
      {
        "url": "https://taller-wox.fitlabs.dev/api/reports/"
      }
    ],
    "paths": {
      "/generate-report": {
        "post": {
          "summary": "Generate Performance Report",
          "description": "This API generates a custom HTML performance report using predefined or user-defined layout sections.\n\n### How It Works\nThe input is a JSON-encoded list (`layout_config`) that specifies the structure of the report. Each item in the list must be one of:\n\n1. A **string**, such as \"care_report\", referring to a predefined layout preset.\n2. A **dictionary**, with:\n   - `element_type`: The name of the registered element (e.g., `header`, `overview`).\n   - `parameters`: A dictionary of arguments for that element function.\n\n### Predefined Presets\n- \"care_report\": A ready-to-use layout including a report header, overview generated by a language model, a claim review chart, and a data table from a CSV file.\n\n### Available Element Types\n\n#### ✅ `header`\n- **Description**: Creates a centered H2 title.\n- **Parameters**:\n  - `title` (string, required): Text to display in the header.\n- **Example**:\n  ```json\n  {\n    \"element_type\": \"header\",\n    \"parameters\": {\n      \"title\": \"Monthly Summary\"\n    }\n  }\n  ```\n\n#### ✅ `overview`\n- **Description**: Uses a prompt + text file to generate a markdown-based summary via a language model.\n- **Parameters**:\n  - `prompt` (string, required): Prompt prepended to the file contents.\n  - `text_file` (string, required): Path to the `.txt` file to append to the prompt.\n  - `title` (string, required): Display title for the section.\n- **Example**:\n  ```json\n  {\n    \"element_type\": \"overview\",\n    \"parameters\": {\n      \"prompt\": \"Summarize customer sentiment: \",\n      \"text_file\": \"./data/combined_email.txt\",\n      \"title\": \"Customer Overview\"\n    }\n  }\n  ```\n\n#### ✅ `claim_review_chart`\n- **Description**: Visualizes synthetic insurance payment breakdowns for multiple CPT codes.\n- **Parameters**: none required\n- **Example**:\n  ```json\n  {\n    \"element_type\": \"claim_review_chart\",\n    \"parameters\": {}\n  }\n  ```\n\n#### ✅ `table`\n- **Description**: Renders a CSV as a Plotly HTML table.\n- **Parameters**:\n  - `csv_file` (string, required): Path to the `.csv` file.\n  - `title` (string, required): Title for the visualization.\n- **Example**:\n  ```json\n  {\n    \"element_type\": \"table\",\n    \"parameters\": {\n      \"csv_file\": \"./data/aetna_claim_review_summary.csv\",\n      \"title\": \"Claim Review Table\"\n    }\n  }\n  ```\n\n### 🧩 Layout Input Format\n- You may nest arrays or mix strings and dictionaries.\n- Only one level of nesting is resolved.\n- Final structure is flattened and rendered in order.\n\n### 🚨 File Usage Rules\n- Files must be located in the `./data/` directory.\n- Approved file types and paths:\n  - `.txt`: For use with `overview`\n    - `./data/combined_email.txt`\n    - `./data/provider_email.txt`\n    - `./data/aetna_email.txt`\n  - `.csv`: For use with `table`\n    - `./data/aetna_claim_review_summary.csv`\n\n⚠️ Do not reuse or cross-reference files across incompatible element types.\n\n### 🔁 Example Full Report Layout\n```json\n[\n  \"care_report\",\n  {\n    \"element_type\": \"header\",\n    \"parameters\": { \"title\": \"End of Report\" }\n  }\n]\n```",
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "layout_config": {
                      "type": "string",
                      "description": "A JSON-encoded string representing a list of section keys and/or custom report elements."
                    }
                  },
                  "required": ["layout_config"]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "The HTML report was successfully generated and uploaded.",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "public_url": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://your-bucket.cloud-object-storage.appdomain.cloud/reports/report.html"
                      }
                    }
                  }
                }
              }
            },
            "500": {
              "description": "An error occurred while generating the report.",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }