AUTO-PART-039 End-to-End Example

Overview

AUTO-PART-039, Determine Core Charge Handling, determines how to handle a core charge, core return, or core credit decision.

Decision ID: AUTO-PART-039
Decision Name: Determine Core Charge Handling
Industry Profile: auto-parts-determine-core-charge-handling-auto-part-039 version 1.0.0
Default Profile: balanced
Default Scenario: standard
Catalog: DKR-AUTO-RUNTIME-001, version 13.9.3

The deterministic Decision Engine ranks eligible core handling options. AI explanation text, when returned, is explanatory only and must not choose, rerank, or override the deterministic result.

Understanding This Decision

Determine Core Charge Handling helps Core & Returns teams compare candidate core handling options using core condition, return timeliness, supplier credit likelihood, customer policy compliance, financial exposure, and customer relationship impact.

Business question

Which core handling option should be recommended for determine core charge handling in the selected Auto Parts context?

Expected outcome

A recommended core handling option or ranked set of core handling options with the criteria and constraints that most influenced the result.

Typical users

Parts operations managers, returns teams, supplier credit teams, counter service teams, compliance reviewers, and integration teams building parts-order workflows.

Decision boundary

Use this decision to compare submitted core handling options. It supports business judgment and does not replace required legal, title, compliance, or management approvals.

Architecture

Request a token from the Identity service.
Use the returned jwtToken as the bearer token.
Load the catalog and decision detail from DKS.
Build a Prepared Decision Input using canonical criterion IDs.
Execute the decision through DDE.
Use X-Request-Id and X-Correlation-Id for tracing across DDE and DKS.

Token propagation: when DDE needs authoritative decision metadata during execution, it forwards the caller's bearer token to DKS with the request identifiers. This lets the catalog and execution records share the same security and tracing context.

Authentication

Request a secure session token from Identity. The current token response field is jwtToken.

Token request

POST https://identity.vinquery.com/connect/token
Content-Type: application/json

{
  "clientId": "{clientId}",
  "clientSecret": "{clientSecret}",
  "audience": "vinquery:api:decisioq"
}

Catalog Discovery

Use DKS to discover the catalog and then load complete metadata for AUTO-PART-039.

Catalog

GET https://dks.vinquery.com/decisioncatalog
Authorization: Bearer {jwtToken}

Decision Detail

GET https://dks.vinquery.com/decisioncatalog/decisions/AUTO-PART-039
Authorization: Bearer {jwtToken}

Criteria

Criterion IDs are intentionally stable machine identifiers. Display labels are for users; request values should be keyed by canonical criterionId.

Criterion ID	Name	Direction	Weight	Validation
`core_condition_score`	Core Condition Score	maximize	25	`score_0_to_100`
`return_timeliness_score`	Return Timeliness Score	maximize	15	`score_0_to_100`
`supplier_credit_likelihood`	Supplier Credit Likelihood	maximize	20	`score_0_to_100`
`customer_policy_compliance`	Customer Policy Compliance	maximize	15	`score_0_to_100`
`financial_exposure`	Financial Exposure	minimize	15	`non_negative_currency`
`relationship_impact_score`	Relationship Impact Score	maximize	10	`score_0_to_100`

Constraint Processing

This decision includes one catalog-defined hard constraint. DKS returns the constraint with the decision detail, and DDE evaluates it before criteria-based ranking.

Verified Catalog Constraint	Status	Effect
`AUTO-PART-039-POLICY-COMPLIANCE-MIN-70`	Hard, enabled, mandatory	Requires `customer_policy_compliance >= 70` before a candidate can participate in ranking.

Eligible and Excluded Candidates

{
  "constraintSummary": {
    "definedConstraintCount": 1,
    "activeConstraintCount": 1,
    "eligibleOptionCount": 2,
    "excludedOptionCount": 1,
    "eligibleOptions": [
      "option-1",
      "option-2"
    ],
    "excludedOptions": [
      {
        "optionId": "option-3",
        "reasons": [
          "Customer policy compliance is below the minimum threshold of 70."
        ]
      }
    ]
  }
}

Constraint Handling Pattern

const constraints = decisionDetail.constraints || [];
if (constraints.length > 0) {
  // DDE applies catalog constraints before ranking.
  // Excluded candidates appear in response.constraintSummary.excludedOptions.
}

const summary = response.constraintSummary;
const excluded = response.decisionResult?.excludedOptions || [];

Excluded candidates do not participate in ranking because hard constraints are evaluated before scoring. For AUTO-PART-039, option-3 is excluded from the showcase sample because its customer policy compliance is below the catalog threshold.

Industry Profile

The generated integration asset uses $.partsOrders as the business options path, $.optionId as the option ID, and $.name as the option display name.

Business Data Path	Criterion ID
`option.assessment.coreConditionScore`	`core_condition_score`
`option.schedule.returnTimelinessScore`	`return_timeliness_score`
`option.core.and.returns.supplierCreditLikelihood`	`supplier_credit_likelihood`
`option.risk.customerPolicyCompliance`	`customer_policy_compliance`
`option.financial.financialExposure`	`financial_exposure`
`option.assessment.relationshipImpactScore`	`relationship_impact_score`

Business Data Fragment

{
  "partsOrders": [
    {
      "optionId": "option-1",
      "name": "Full Core Credit",
      "assessment": {
        "coreConditionScore": 80,
        "relationshipImpactScore": 80
      },
      "schedule": {
        "returnTimelinessScore": 80
      },
      "core": {
        "and": {
          "returns": {
            "supplierCreditLikelihood": 80
          }
        }
      },
      "risk": {
        "customerPolicyCompliance": 80
      },
      "financial": {
        "financialExposure": 1500
      }
    }
  ]
}

Prepared Option Values

{
  "optionId": "option-1",
  "name": "Full Core Credit",
  "values": {
    "core_condition_score": 80,
    "return_timeliness_score": 80,
    "supplier_credit_likelihood": 80,
    "customer_policy_compliance": 80,
    "financial_exposure": 1500,
    "relationship_impact_score": 80
  }
}

Profiles and Scenarios

A profile changes criterion weights. A scenario describes the operating context for the execution. The active DKS catalog exposes these choices with the decision detail response.

Profile ID	Name	Purpose
`balanced`	Balanced	Preserves the default DKS criterion weights.
`cost_focused`	Cost Focused	Places stronger emphasis on price, margin, carrying cost, fulfillment cost, and other financial criteria.
`service_focused`	Service Focused	Places stronger emphasis on availability, customer urgency, fill rate, delivery promise, and customer experience criteria.
`risk_averse`	Risk Averse	Places stronger emphasis on compatibility, warranty exposure, return risk, stockout risk, and operational uncertainty.

Scenario ID	Name	Use When
`standard`	Standard Operating Scenario	Normal operating context for routine parts sales and customer service decision execution.
`stock_constrained`	Stock-Constrained Scenario	Use when inventory is limited, backorders are high, or allocation discipline is required.
`urgent_customer_need`	Urgent Customer Need Scenario	Use when customer downtime, repair urgency, or service-level commitments are more important than normal.
`margin_protection`	Margin Protection Scenario	Use when price discipline, margin preservation, or credit exposure must be controlled more aggressively.

Prepared Input

For Prepared Decision Input, send decisionId, selected profile/scenario IDs, and option values keyed by canonical criterion ID. This request intentionally does not duplicate values under display labels.

Prepared Decision Input JSON

{
  "decisionId": "AUTO-PART-039",
  "profileId": "balanced",
  "scenarioId": "standard",
  "algorithm": "TOPSIS",
  "weightStrategy": "Manual",
  "runSensitivity": false,
  "requestContext": {
    "correlationId": "auto-part-039-demo-001"
  },
  "options": [
    {
      "optionId": "option-1",
      "name": "Full Core Credit",
      "values": {
        "core_condition_score": 80,
        "return_timeliness_score": 80,
        "supplier_credit_likelihood": 80,
        "customer_policy_compliance": 80,
        "financial_exposure": 1500,
        "relationship_impact_score": 80
      }
    },
    {
      "optionId": "option-2",
      "name": "Partial Core Credit",
      "values": {
        "core_condition_score": 73,
        "return_timeliness_score": 73,
        "supplier_credit_likelihood": 73,
        "customer_policy_compliance": 73,
        "financial_exposure": 1950,
        "relationship_impact_score": 73
      }
    },
    {
      "optionId": "option-3",
      "name": "Core Charge Retained",
      "values": {
        "core_condition_score": 66,
        "return_timeliness_score": 66,
        "supplier_credit_likelihood": 66,
        "customer_policy_compliance": 66,
        "financial_exposure": 2400,
        "relationship_impact_score": 66
      }
    }
  ]
}

Execute

cURL

curl -X POST "https://dde.vinquery.com/api/v1/decide" \
  -H "Authorization: Bearer ${DECISIOQ_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: auto-part-039-demo-001" \
  --data @auto-part-039-execute.json

DDE retrieves authoritative criteria, validation metadata, and constraints from DKS, excludes candidates that fail mandatory hard constraints, executes the deterministic ranking, and returns the decision result plus execution metadata.

Interpret the Result

The successful response is centered on decisionResult. The winner and ranking are deterministic outputs; optional explanation fields add context but do not change the ranking.

Successful Response Shape

{
  "service": "decisioq",
  "version": "7.6.3",
  "requestId": "0HNE...",
  "operation": "Decide",
  "success": true,
  "decisionType": "AUTO-PART-039",
  "decisionVersion": "13.9.3",
  "timestampUtc": "2026-07-19T00:00:00Z",
  "decisionResult": {
    "winner": "option-1",
    "confidence": 91,
    "ranking": [
      {
        "optionId": "option-1",
        "score": 0.91,
        "breakdown": {
          "core_condition_score": 0.25,
          "return_timeliness_score": 0.15,
          "supplier_credit_likelihood": 0.20,
          "customer_policy_compliance": 0.15,
          "financial_exposure": 0.15,
          "relationship_impact_score": 0.10
        },
        "normalizationBreakdown": {}
      },
      {
        "optionId": "option-2",
        "score": 0.84,
        "breakdown": {},
        "normalizationBreakdown": {}
      }
    ],
    "excludedOptions": [
      {
        "optionId": "option-3",
        "reasons": [
          "Customer policy compliance is below the minimum threshold of 70."
        ]
      }
    ],
    "explanation": {
      "summary": "Full Core Credit ranked highest among eligible core handling options.",
      "strengths": [],
      "weaknesses": [],
      "exclusions": [
        "option-3: Customer policy compliance is below the minimum threshold of 70."
      ]
    }
  },
  "constraintSummary": {
    "definedConstraintCount": 1,
    "activeConstraintCount": 1,
    "eligibleOptionCount": 2,
    "excludedOptionCount": 1,
    "eligibleOptions": [
      "option-1",
      "option-2"
    ],
    "excludedOptions": [
      {
        "optionId": "option-3",
        "reasons": [
          "Customer policy compliance is below the minimum threshold of 70."
        ]
      }
    ]
  },
  "warnings": [],
  "requestContext": {
    "correlationId": "auto-part-039-demo-001"
  }
}

WinnerThe selected option ID in decisionResult.winner.

RankingOnly eligible options ordered by deterministic score.

ExclusionsHard-constraint failures listed under constraintSummary and decisionResult.excludedOptions.

Sensitivity Analysis

Set runSensitivity to true on catalog execution when the client wants recommendation-stability information in the same response. The sensitivity engine perturbs criterion weights by controlled factors and reports whether the winner remains stable.

Sensitivity Result Shape

{
  "sensitivityResult": {
    "stableWinner": true,
    "winner": "option-1",
    "mostSensitiveCriterion": "return_timeliness_score",
    "confidence": 95,
    "criterionImpacts": {
      "return_timeliness_score": 0.1842
    },
    "winnerChangeCounts": {
      "return_timeliness_score": 0
    }
  }
}

Use sensitivity output to decide whether a recommendation is robust enough for automation or should be reviewed by a person.

Explanation of Decision Result

Every successful response can include deterministic explanation text under decisionResult.explanation and explanation. When the Explanation Service is enabled, the response may also include an ai block with structured business-language explanation fields.

Explanation Shape

{
  "ai": {
    "enabled": true,
    "generated": true,
    "schemaValidated": true,
    "explanation": {
      "summary": "The selected core handling option provided the strongest overall balance of core condition, return timeliness, supplier credit likelihood, customer policy compliance, financial exposure, and relationship impact.",
      "whyRecommended": "It met the hard customer policy compliance threshold and ranked highest among eligible core handling options.",
      "keyDrivers": [],
      "tradeoffs": [],
      "competitors": [],
      "sensitivitySummary": "Sensitivity analysis was not included in this response.",
      "scenarioSummary": "The standard scenario was selected.",
      "risks": [],
      "nextSteps": [],
      "assumptions": []
    }
  }
}

Explanation output is supporting context. Business-facing pages should render the explanation, warnings, assumptions, and limitations without provider branding.

Tracing and Logs

Use request identifiers to connect client, catalog, and execution activity during support or integration testing.

X-Request-Id: Optional client-supplied request ID. If omitted, the server generates one.
X-Correlation-Id: Optional client correlation value propagated from DDE to DKS.
requestContext.correlationId: Optional payload value echoed in the response and used for tracing.
executionTrace: Advanced execution metadata including selected profile, selected scenario, effective weights, and applied constraints.

Code Examples

These examples demonstrate the current DecisioQ flow:

Request jwtToken from https://identity.vinquery.com/connect/token.
Load AUTO-PART-039 metadata from https://dks.vinquery.com/decisioncatalog/decisions/AUTO-PART-039.
Execute a Prepared Decision Input at https://dde.vinquery.com/api/v1/decide.

Set these environment variables before running any companion example:

Environment variables

DECISIOQ_CLIENT_ID
DECISIOQ_CLIENT_SECRET

Optional:
DECISIOQ_AUDIENCE=vinquery:api:decisioq
DECISIOQ_IDENTITY_URL=https://identity.vinquery.com/connect/token
DECISIOQ_DKS_URL=https://dks.vinquery.com
DECISIOQ_DDE_URL=https://dde.vinquery.com

Download the source files directly:

README.mdSetup and run notes Prepared Input JSONShared request payload cURL shell scriptrun-auto-part-039.sh C# Program.cs.NET 8 console example JavaScriptNode.js module TypeScriptTyped fetch example PythonStandard library example PHPcURL extension example Gonet/http example Javajava.net.http example

Troubleshooting

Symptom	Likely Cause	What to Check
401 Unauthorized	Missing, expired, or invalid bearer token.	Request a fresh `jwtToken` from Identity and send it as `Authorization: Bearer ...`.
Decision not found	The decision ID is not in the active catalog.	Load `/decisioncatalog/decisions/AUTO-PART-039` and confirm the ID is published.
Validation failed	A required criterion value is missing or outside its rule.	Use canonical criterion IDs and keep score values in the expected range.
Candidate excluded	A mandatory hard constraint failed.	Review `constraintSummary.excludedOptions` for the exact candidate and reason.
HTML error response	An upstream hosted service failed before returning JSON.	Check service health and server logs for Identity, DKS, or DDE.

Production Checklist

Security

Keep API Consumer credentials and jwtTokens on the server side. Use HTTPS, short-lived bearer tokens, and an API Consumer linked to a DecisioQ account for usage accounting.

Catalog

Load decision metadata from DKS and cache cautiously. Refresh when catalog versions change.

Request Quality

Use canonical criterion IDs, validate value ranges, and send at least two candidate options.

Constraints

Show excluded candidates separately. Do not include them in user-facing ranking tables.

Explanation

Display explanation text as supporting context only. Never let AI text override deterministic results.

User Experience

Show business labels to users and keep raw execution trace collapsed for advanced diagnostics.