Analytics: Report Generation

Problem Statement

Generating reports involves selecting data sources, date ranges, metrics, and output format. Reports may take time to process (async) and produce downloadable files.

Why Human-Only Semantics Fail

• Report builder UIs are multi-step wizards
• Available metrics depend on selected data sources
• Output format options (PDF, CSV, XLSX) aren't declared as parameters
• Processing time is shown with spinners, not structured status

Why Scraping Fails Here

• Report generation is asynchronous — results aren't immediate
• Download links are temporary, signed URLs
• Complex reports trigger server-side processing jobs
• Progress indicators are JavaScript-driven animations

How AXAG Eliminates Scraping

report.generate declares it as an async operation with a defined output format enum. Agents poll for completion using report.status.

Annotated UI Example

Analytics — generate report (async)

<button
  axag-intent="report.generate"
  axag-entity="report"
  axag-action-type="write"
  axag-required-parameters='["report_type","date_range"]'
  axag-optional-parameters='["metrics","dimensions","format","filters"]'
  axag-postconditions='["report generation job created"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-async="true"
  axag-scope="tenant"
  axag-description="Generate an analytics report"
>Generate Report</button>

Semantic Manifest Excerpt

Manifest — report.generate

{
  "intent": "report.generate",
  "entity": "report",
  "action_type": "write",
  "operation_id": "report_generate",
  "description": "Generate an analytics report",
  "required_parameters": [
    {
      "name": "report_type",
      "type": "string",
      "enum": ["summary", "detailed", "comparison", "trend"]
    },
    {
      "name": "date_range",
      "type": "object",
      "properties": {
        "start": { "type": "string", "format": "date" },
        "end": { "type": "string", "format": "date" }
      }
    }
  ],
  "optional_parameters": [
    { "name": "metrics", "type": "array", "items": { "type": "string" } },
    { "name": "dimensions", "type": "array", "items": { "type": "string" } },
    {
      "name": "format",
      "type": "string",
      "enum": ["pdf", "csv", "xlsx", "json"],
      "default": "json"
    },
    { "name": "filters", "type": "object" }
  ],
  "risk_level": "low",
  "idempotent": false,
  "async": true,
  "scope": "tenant",
  "postconditions": ["report generation job created"]
}

Generated Tool Example

{
  "name": "report_generate",
  "description": "Generate an analytics report (async — returns job ID)",
  "input_schema": {
    "type": "object",
    "properties": {
      "report_type": { "type": "string", "enum": ["summary", "detailed", "comparison", "trend"] },
      "date_range": {
        "type": "object",
        "properties": {
          "start": { "type": "string", "format": "date" },
          "end": { "type": "string", "format": "date" }
        },
        "required": ["start", "end"]
      },
      "metrics": { "type": "array", "items": { "type": "string" } },
      "format": { "type": "string", "enum": ["pdf", "csv", "xlsx", "json"], "default": "json" }
    },
    "required": ["report_type", "date_range"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "async": true,
    "source_intent": "report.generate",
    "source_entity": "report"
  }
}

Constraints & Safety Notes

• Async operation: returns a job ID, not the report itself
• Agent should poll report.status with the job ID to check completion
• Not idempotent — each call creates a new report job
• json is the preferred agent format; PDF/XLSX are for human consumption
• Scoped to tenant data only