PowerDecision Tutorials

Overview

These hands-on tutorials walk you through PowerDecision from first use to production deployment. Each tutorial builds on the previous one.

Tutorial 1: First Decision Model

In this tutorial you'll upload a pre-built loan approval template and execute your first decision.

Prerequisites

• PowerDecision running on http://localhost:8031
• Redis running on localhost:6379 (or 6381 if using Docker Compose)
• A terminal with curl or any HTTP client

Verify the service is healthy:

curl http://localhost:8031/health/liveness

Expected response:

{"status": "UP"}

Step 1: Upload the Loan Approval Template

PowerDecision ships with decision templates in the decision-templates/ directory. Upload the loan approval template:

curl -X POST http://localhost:8031/api/powerdecision/v1/models/upload \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "loan_approval",
    "name": "Loan Approval",
    "description": "Evaluates loan applications based on credit score, income, and employment",
    "version": "1.0",
    "inputs_schema": [
      { "name": "credit_score", "type": "number" },
      { "name": "annual_income", "type": "number" },
      { "name": "loan_amount", "type": "number" },
      { "name": "employment_status", "type": "string" },
      { "name": "debt_to_income", "type": "number" },
      { "name": "loan_purpose", "type": "string" }
    ],
    "outputs_schema": [
      { "name": "approval_status", "type": "string" },
      { "name": "max_loan_amount", "type": "number" },
      { "name": "interest_rate", "type": "number" },
      { "name": "reason", "type": "string" }
    ],
    "policy": "FIRST",
    "rules": [
      {
        "conditions": [
          { "input": "credit_score", "operator": "gte", "value": 750 },
          { "input": "employment_status", "operator": "eq", "value": "employed" }
        ],
        "outputs": {
          "approval_status": "approved",
          "max_loan_amount": 500000,
          "interest_rate": 3.5,
          "reason": "Excellent credit with stable employment"
        },
        "priority": 1
      },
      {
        "conditions": [
          { "input": "credit_score", "operator": "between", "value": [650, 749] },
          { "input": "debt_to_income", "operator": "lt", "value": 0.4 }
        ],
        "outputs": {
          "approval_status": "approved",
          "max_loan_amount": 300000,
          "interest_rate": 5.0,
          "reason": "Good credit with acceptable debt ratio"
        },
        "priority": 2
      },
      {
        "conditions": [
          { "input": "credit_score", "operator": "lt", "value": 650 }
        ],
        "outputs": {
          "approval_status": "denied",
          "max_loan_amount": 0,
          "interest_rate": 0,
          "reason": "Credit score below minimum threshold"
        },
        "priority": 3
      },
      {
        "conditions": [],
        "outputs": {
          "approval_status": "review",
          "max_loan_amount": 100000,
          "interest_rate": 7.0,
          "reason": "Manual review required"
        },
        "priority": 99
      }
    ]
  }'

You should see:

{
  "model_id": "loan_approval",
  "version": "1.0",
  "status": "uploaded",
  "message": "Model uploaded and DMN generated successfully"
}

Step 2: Submit a Decision

Now submit a decision request with sample inputs:

curl -X POST http://localhost:8031/api/powerdecision/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "loan_approval",
    "inputs": {
      "credit_score": 720,
      "annual_income": 85000,
      "loan_amount": 250000,
      "employment_status": "employed",
      "debt_to_income": 0.28,
      "loan_purpose": "home_purchase"
    }
  }'

Response:

{
  "jobId": "dec-a1b2c3d4",
  "status": "PENDING"
}

Save the jobId — you'll need it to retrieve the result.

Step 3: Poll for Results

Decision evaluation is asynchronous. Poll with the job ID:

curl http://localhost:8031/api/powerdecision/v1/decisions/dec-a1b2c3d4

When complete, you'll see the full result:

{
  "model_id": "loan_approval",
  "version": "1.0",
  "status": "SUCCESS",
  "decision": {
    "approval_status": "approved",
    "max_loan_amount": 300000,
    "interest_rate": 5.0,
    "reason": "Good credit with acceptable debt ratio"
  },
  "explanation": "Rule 2 matched",
  "metadata": {
    "evaluation_time_ms": 42,
    "hit_policy": "FIRST",
    "rules_evaluated": 4,
    "rules_matched": 1
  }
}

Tutorial 2: Using Decision Templates

PowerDecision includes 7 pre-built templates for common business decisions. This tutorial shows how to browse, upload, and customize them.

Browse Available Templates

Templates are JSON files in the decision-templates/ directory:

Upload and Test a Template

Upload the fraud detection template:

# Upload from the templates directory (adjust path as needed)
curl -X POST http://localhost:8031/api/powerdecision/v1/models/upload \
  -H "Content-Type: application/json" \
  -d @decision-templates/fraud_detection.json

Test with a suspicious transaction:

curl -X POST http://localhost:8031/api/powerdecision/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "fraud_detection",
    "inputs": {
      "transaction_amount": 9500,
      "location_risk": "high",
      "device_known": false,
      "time_of_day": "03:00",
      "velocity_24h": 12
    }
  }'

Customize a Template

Templates are starting points. Customize them for your business:

1. Copy the template JSON and give it a new model_id
2. Modify input fields — Add or remove inputs to match your data
3. Adjust rules — Change condition thresholds (e.g., credit score cutoffs)
4. Update outputs — Add output columns for your specific needs
5. Change hit policy — Switch from FIRST to COLLECT if you need all matching rules
6. Upload the customized version with a new model_id

Tutorial 3: Wizard to Production

This tutorial walks through creating a custom decision model in the wizard, uploading it, and validating it for production use.

Step 1: Design in the Wizard

Open the Decision Wizard and create a support ticket routing model:

1. Model Info:
   • Model ID: my_ticket_router
   • Name: "Support Ticket Router"
   • Version: "1.0"
2. Define Inputs:
   • priority (string) — allowed values: low, medium, high, critical
   • category (string) — allowed values: billing, technical, account, general
   • customer_tier (string) — allowed values: free, pro, enterprise
3. Define Outputs:
   • team (string) — which support team handles it
   • sla_hours (number) — response SLA in hours
   • escalation (boolean) — whether to auto-escalate
4. Hit Policy: FIRST (return the highest-priority matching rule)
5. Add Rules:
   • Critical + Enterprise → escalation team, 1 hour SLA, auto-escalate
   • High + Technical → engineering team, 4 hours SLA
   • Billing (any priority) → billing team, 8 hours SLA
   • Default → general support, 24 hours SLA

Step 2: Upload to API

From the wizard's Review step, click Submit to API. The wizard sends the JSON to the upload endpoint. Alternatively, export the JSON and upload via curl:

curl -X POST http://localhost:8031/api/powerdecision/v1/models/upload \
  -H "Content-Type: application/json" \
  -d @my_ticket_router.json

Verify the model was uploaded:

curl http://localhost:8031/api/powerdecision/v1/models

You should see my_ticket_router in the models list.

Step 3: Validate and Test

Test each rule path to ensure correct behavior:

Test 1 — Critical enterprise ticket:

curl -X POST http://localhost:8031/api/powerdecision/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "my_ticket_router",
    "inputs": {
      "priority": "critical",
      "category": "technical",
      "customer_tier": "enterprise"
    }
  }'

Expected: team=escalation, sla_hours=1, escalation=true

Test 2 — Billing inquiry:

curl -X POST http://localhost:8031/api/powerdecision/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "my_ticket_router",
    "inputs": {
      "priority": "low",
      "category": "billing",
      "customer_tier": "free"
    }
  }'

Expected: team=billing, sla_hours=8, escalation=false

Test 3 — Default catch-all:

curl -X POST http://localhost:8031/api/powerdecision/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "my_ticket_router",
    "inputs": {
      "priority": "low",
      "category": "general",
      "customer_tier": "pro"
    }
  }'

Expected: team=general_support, sla_hours=24, escalation=false

Tutorial 4: PDP Pipeline Integration

PowerDecision is the "Decide" stage in the Predict-Decide-Plan (PDP) pipeline orchestrated by PowerOrchestrator. This tutorial shows how the integration works.

Architecture Overview

In the PDP pipeline, PowerDecision receives forecast outputs and produces decisions that feed into the planning stage:

PowerForecast          PowerDecision           PowerSolver
(Predict)     ──▶     (Decide)        ──▶     (Plan)
                         │
                         ▼
                   capacity_adjustment
                   model evaluates
                   forecast results

The orchestrator calls PowerDecision through the standard Platform Contract:

• Request: The orchestrator sends a DecisionSpec with the model_id and inputs derived from the forecast stage output
• Response: PowerDecision returns a DecisionResult with the decision outputs
• Async pattern: Submit → poll with job ID → retrieve result

Configure the Decision Stage

In the PowerOrchestrator pipeline definition, the decision stage is configured as:

{
  "stage_type": "DECISION",
  "product": "PowerDecision",
  "config": {
    "model_id": "capacity_adjustment",
    "version": "1.0",
    "timeout_seconds": 30,
    "retry_count": 2
  }
}

The orchestrator manages:

• Input mapping — Transforms forecast outputs into decision inputs
• Job submission — POSTs to /api/powerdecision/v1/decisions
• Polling — GETs /api/powerdecision/v1/decisions/{jobId} until terminal state
• Timeout handling — Enforces the configured timeout
• Retry logic — Retries on failure up to the configured count
• Output mapping — Passes decision outputs to the planning stage

Run a Full Pipeline

With PowerOrchestrator running on port 8050:

# Submit a PDP pipeline run
curl -X POST http://localhost:8050/pdp/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_name": "default_pdp",
    "config": {
      "ai_validate_forecast": true,
      "ai_briefing": true
    }
  }'

Monitor the pipeline run to see the decision stage execute:

# Get pipeline run status
curl http://localhost:8050/pdp/runs/{run_id}

The response includes stage details showing PowerDecision's contribution:

{
  "stages": [
    {
      "stage_type": "FORECAST",
      "status": "COMPLETED",
      "product_job_id": "fc-abc123"
    },
    {
      "stage_type": "DECISION",
      "status": "COMPLETED",
      "product_job_id": "dec-def456",
      "execution_time_ms": 245,
      "response": {
        "decision": {
          "capacity_action": "increase",
          "adjustment_percentage": 15,
          "confidence": 0.87
        }
      }
    },
    {
      "stage_type": "PLANNING",
      "status": "RUNNING",
      "product_job_id": "sol-ghi789"
    }
  ]
}