DEMO_API_README.md

# Mixed Workflow Demo API Documentation

This document outlines the APIs available for the interactive Mixed Workflow Demo. These endpoints allow a web frontend to fetch the available workflow components and execute an end-to-end demo pipeline (UDF → Rule → ML) without requiring a live database or actual machine learning models.

## Location
The demo APIs are defined in the backend codebase at:
`c:\Users\swastik\prediqai\RULE\workflow\demo\demo_api.py`

## Base URL
Depending on how the backend server is started, the base URL for these endpoints will be:
- **Standalone Demo Server:** `http://localhost:8001`
- **Integrated within Main App:** `http://localhost:7860/workflow` (if optionally integrated in `app.py`)

---

## 1. Fetch Demo Catalog

Retrieves all available demo features that the user can select on the frontend to build their workflow.

- **Endpoint:** `GET /demo/catalog`
- **Method:** `GET`
- **Description:** Returns the available dummy UDFs, Rules, and ML Models configurations. Use this endpoint to populate dropdowns or selection cards in the UI.

### Success Response (200 OK)

```json
{
  "udfs": {
    "clean_names": "Removes special characters and lowercases names",
    "extract_domain": "Extracts the email domain into a new column"
  },
  "rules": {
    "high_value_tx": "Flags transactions over $10k",
    "suspicious_country": "Flags transactions from restricted countries"
  },
  "ml_models": {
    "fraud_detection_v1": "Predicts fraud probability for financial transactions",
    "churn_prediction": "Predicts customer churn probability"
  }
}
```

---

## 2. Run Demo Workflow

Executes a sequenced three-step mock workflow: exactly one **UDF** -> one **Rule** -> one **ML Model**.

- **Endpoint:** `POST /demo/run`
- **Method:** `POST`
- **Headers:** `Content-Type: application/json`
- **Description:** Runs the selected steps sequentially on a dummy dataset and returns a sample output dataframe showing added columns, and logging of execution steps.

### Request Body

```json
{
  "udf": "clean_names",
  "rule": "high_value_tx",
  "ml_model": "fraud_detection_v1",
  "dummy_ml_port": 18765
}
```

*Note: `dummy_ml_port` is optional and defaults to 18765. It's the port where the backend spins up the dummy ML predicting API locally.*

### Success Response (200 OK)

Returns execution statistics, columns added during processing, and a sample array of the enriched final dataset records.

```json
{
  "status": "success",
  "steps": [
    { "type": "udf", "name": "clean_names" },
    { "type": "rule", "name": "high_value_tx" },
    { "type": "ml", "name": "fraud_detection_v1" }
  ],
  "rows_processed": 1000,
  "final_rows": 1000,
  "columns_added": ["cleaned_name", "flag_high_value", "fraud_prob", "fraud_prediction"],
  "sample": [
    {
      "name": "john_doe",
      "amount": 15000,
      "country": "US",
      "transaction_type": "transfer",
      "cleaned_name": "john doe",
      "flag_high_value": true,
      "fraud_prob": 0.85,
      "fraud_prediction": 1
    }
  ]
}
```

### Error Responses

#### Validation Error (400 Bad Request)
Triggered if an unknown component is provided.
```json
{
  "status": "error",
  "step": "validation",
  "error": "Unknown UDF 'invalid_udf_name'. Available: ['clean_names', 'extract_domain']"
}
```

#### Execution Error (400 or 500 Internal Server Error)
Triggered if any of the workflow engine steps fails internally.
```json
{
  "status": "error",
  "step": "Workflow",
  "error": "Failed to apply rule constraints."
}
```