AI API

AI-powered assistance and metadata generation endpoints.

Endpoints Overview

Method	Endpoint	Description
POST	/ai/generate-description	Generate product description
POST	/ai/generate-field-description	Generate field description
POST	/ai/suggest-tags	Suggest tags for product
POST	/alerts/{id}/explain	Generate anomaly explanation

---

Generate Product Description

POST /ai/generate-description

Request Body

{
  "product_name": "customer_events",
  "fields": ["user_id", "event_type", "timestamp", "properties"],
  "context": "Part of the analytics warehouse"
}

Response

{
  "description": "Captures user interaction events from the web and mobile applications. Contains event metadata including user identification, event categorization, and custom properties for behavioral analysis.",
  "confidence": 0.85
}

---

Generate Field Description

POST /ai/generate-field-description

{
  "field_name": "customer_lifetime_value",
  "data_type": "DECIMAL",
  "table_name": "customers",
  "sample_values": ["150.00", "2500.50", "89.99"]
}

Response

{
  "description": "The total revenue attributed to a customer over their entire relationship with the business, calculated as the sum of all purchases.",
  "confidence": 0.78
}

---

Suggest Tags

POST /ai/suggest-tags

{
  "product_name": "order_transactions",
  "description": "Contains all order records from the e-commerce platform"
}

Response

{
  "tags": ["commerce", "transactions", "orders", "revenue"],
  "confidence": 0.82
}

---

Explain Anomaly Alert

POST /alerts/{id}/explain

Generates an AI-powered root-cause hypothesis for an anomaly or trend alert. The service gathers context signals — sync events, upstream anomalies, quality check failures, and schema drift — then calls the LLM to produce an explanation.

Results are cached in the alert's metadata. Subsequent calls return the cached explanation without re-invoking the LLM.

Path Parameters

Parameter	Type	Description
id	UUID	Alert ID (must be anomaly or trend type)

Response

{
  "explanation": "The anomaly appears to be caused by a failed sync event on the upstream orders connector at 14:32 UTC, which resulted in a partial data load missing approximately 40% of expected records.",
  "confidence": "high",
  "contributing_factors": [
    "Upstream connector 'orders_pg' sync failed at 14:32 UTC",
    "Quality check 'row_count_threshold' on orders_daily failed 30 minutes before the alert",
    "No schema changes detected in the analysis window"
  ]
}