PDC data/TRD.md

# Technical Requirements

# Document (TRD)

## Product Development Center (PDC)

## Intelligence Platform

**Prepared by:** Ascentia Labs
**Client Name:** Vardhman Textiles
**Date:** 18th June, 2026
**Version:** 2.3
**Subject:** End-to-end technical blueprint for construction prediction intelligence, client feasibility workflow, AI construction suggestion, and XML export automation.

### Revision History

| Version | Date | Summary |
| ------- | ---- | ------- |
| 2.0 | 20 Apr 2026 | Initial TRD (see `TRD2.pdf` archive) |
| 2.1 | 5 Jun 2026 | 5-case cascade, EPI/PPI probing, distance-weighted aggregation |
| 2.2 | 12 Jun 2026 | **Client feasibility workflow**: GSM count-pair matrix, exact historical article recommendations, selectable count pairs, full dataset table |
| 2.3.1 | 18 Jun 2026 | **Client examples gap (round 2):** single refinement pass after active-pair selection, GSM-closest auto-select tie-break, primary-pair PPI evaluation, formula-first on-loom reed with capped archive median, all 8 spreadsheet examples in golden tests |

> **Note:** `TRD2.pdf` is the archived v2.0 export. Regenerate `TRD.pdf` with: `python3 build_trd_pdf.py`

## 1. Executive Overview

## 1.1 Product Vision

```
The PDC Intelligence Platform is a specialized engineering decision system that transforms customer-side finish
requirements into production-ready greige construction outputs.
```

```
The platform combines:
```

```
Historical Intelligence : Learns from previously executed constructions across Vardhman datasets.
Formula Intelligence : Applies textile engineering formulas (shrinkage reversal, reed-density relationships, cover
factor).
Operational Output : Produces machine-usable construction recommendations and exports structured XML for
downstream CAD workflows.
```

```
This creates a governed, explainable, and repeatable process in place of manual trial-and-error engineering decisions.
```

## 1.2 The Core Business Problem

```
The current construction planning process depends on manual engineering interpretation of historical sheets. This
introduces four recurring operational risks:
```

```
Inconsistent decisions : Similar customer requirements can receive different greige recommendations depending
on engineer memory.
Manual lookup overhead : Historical references are spread across Excel sheets and local knowledge, increasing
cycle time.
Propagation of errors : If an incorrect construction is reused without validation, similar upcoming orders inherit
that risk.
```

```
Weak traceability : Teams cannot always explain why a given construction was selected (historical basis vs
formula basis).
```

```
The system addresses this with a data-driven question:
```

```
“Given this finish requirement, what greige construction should be used, what is the confidence, and how does this
compare against formula-derived expectation?”
```

### 1.3 System Capabilities at a Glance

| Capability                      | Description                                                                                                 |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Construction Intelligence       | Client feasibility workflow: GSM count-pair cases → per-pair cascade search → top 2–3 **exact** historical articles |
| AI Construction Suggestion    | Synthesized greige/onloom/reed construction from finish targets + archive-learned shrinkage (additive to exact matches) |
| GSM Case Selection              | Auto-selects best count pair; user can click any GSM row to switch dataset and refresh recommendations      |
| Confidence & Data Quality       | Labels confidence from archive match depth and best-article score (no CV aggregation)                       |
| Article Intelligence Repository | Searchable archive; active count-pair dataset table with highlighted closest matches                        |
| XML Export Automation           | One-click construction.xml from primary recommended article                                                 |
| Validation Framework            | Holdout-style validation report endpoint to evaluate prediction behavior                                    |

## 2. Product Architecture

### 2.1 System Architecture (Business + Technical View)

```text
┌────────────────────────────────────────────────────────────────────┐

│ WEB APPLICATION │

│ │

│ Dashboard | Prediction Studio | Article Archive | Docs │
│ │
│ + GSM Count-Pair Table (selectable rows) │
│ + Exact-Match Construction Cards │
│ + Full Archive Dataset Table │
│ + XML Export Action │
└───────────────────────────────┬────────────────────────────────────┘
│
↓
┌────────────────────────────────────────────────────────────────────┐
│ INTELLIGENCE & API LAYER │
│ (FastAPI + Pandas) │
│ │
│ 1) Historical Matching Engine │
│ 2) Formula Calculation Engine │
│ 3) Confidence + Validation Engine │
│ 4) XML Generation Engine │
└───────────────────────────────┬────────────────────────────────────┘
│
↓
┌────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ │
│ Working 24 Jan.xlsx (9,352 rows) │
│ Piece Dyed Artcle details.xlsx (1,822 rows) │
│ │
│ Total historical rows analyzed: 11,174 │
└────────────────────────────────────────────────────────────────────┘
```

### 2.2 The Three Core Capability Blocks

#### 2.2.1 The Brain (Intelligence Engine)

```
Purpose: Convert finish targets into construction recommendations using evidence.
```

```
What it does:
```

```
Builds GSM back-calculation count-pair matrix (primary + expanded search).
Runs 5-case cascade per count pair against the article archive.
Ranks articles with weighted absolute-delta scoring; returns exact constructions unchanged.
Lets engineers override the auto-selected count pair and refresh recommendations.
```

```
Business value: Mirrors the client feasibility spreadsheet process — offer the same historical construction to the customer.
```

#### 2.2.2 The Organizer (Knowledge Layer)

```
Purpose: Establish one authoritative reference for previous constructions.
```

```
What it does:
```

```
Consolidates Working and Piece Dyed data into a normalized analysis layer.
Exposes searchable article-level references (article, weave, blend, EPI/PPI, reed-space).
Tracks match source and sample size to improve decision transparency.
```

```
Business value: Eliminates fragmented historical lookup and improves traceability.
```

#### 2.2.3 The Operator (Execution Layer)

```
Purpose: Convert prediction decisions into operational artifacts.
```

```
What it does:
```

```
Presents construction outputs in structured cards.
Displays comparative formula output next to historical recommendation.
Exports construction.xml for CAD-import workflows.
```

```
Business value: Reduces manual re-entry errors and shortens engineering cycle time.
```

## 3. How the System Works (Operational Flow)

### 3.1 End-to-End Prediction Flow (v2.2 — Client Feasibility)

```text
┌────────────────────────────────────────────┐
│ 1. USER INPUT                              │
│ Warp, Weft, Finish EPI/PPI, Weave, Blend,  │
│ Target GSM, Dataset, Weights (tunable)     │
└───────────────────┬────────────────────────┘
                    ↓
┌────────────────────────────────────────────┐
│ 2. GSM COUNT-PAIR MATRIX                   │
│ primary_standard_counts() brackets counts   │
│ GSM = {(EPI/Warp)+(PPI/Weft)} × 24.5       │
│ Primary 4 cases + expanded search if needed  │
└───────────────────┬────────────────────────┘
                    ↓
┌────────────────────────────────────────────┐
│ 3. PER-PAIR CASCADE SEARCH (5+1)           │
│ For each warp×weft pair: filter archive,   │
│ run Case-1…Case-5 cascade, rankable rows   │
└───────────────────┬────────────────────────┘
                    ↓
┌────────────────────────────────────────────┐
│ 4. AUTO-SELECT ACTIVE COUNT PAIR           │
│ Pick GSM-closest pair with ≥3 archive rows │
│ (tie-break: larger match_count)            │
│ User may override by clicking any GSM row    │
└───────────────────┬────────────────────────┘
                    ↓
┌────────────────────────────────────────────┐
│ 5. ARTICLE RANKING                         │
│ Weighted absolute delta on Fin EPI/PPI/GSM │
│ Dedupe by construction fingerprint + family  │
│ Return top 3 exact historical articles     │
└───────────────────┬────────────────────────┘
                    ↓
┌────────────────────────────────────────────┐
│ 6. OUTPUT                                  │
│ GSM table, dataset table, match cards,     │
│ reed alternatives, match summary, XML      │
└────────────────────────────────────────────┘
```

**Design principle (v2.2):** Do not median-aggregate or synthesize a new construction. Return real executed articles so engineers can offer the **same construction** to the customer, per the client feasibility process document.

### 3.2 Example 1: Client Twill Feasibility

```
Input request:
```

```
Warp Count: 21.2
Weft Count: 14.5
Finish EPI: 125
Finish PPI: 60
Weave: 3/1 S TWILL
Blend: 100% Cotton
Target GSM: 235
```

```
GSM count-pair cases (primary):
```

| Case | Warp | Weft | EPI | PPI | GSM |
| ---- | ---- | ---- | --- | --- | --- |
| 1 | 21 | 14 | 125 | 60 | 250.8 |
| 2 | 21 | 16 | 125 | 60 | 237.7 |
| 3 | 20 | 14 | 125 | 60 | 258.1 |
| 4 | 20 | 16 | 125 | 60 | 245.0 |

```
System process:
```

```
1. Builds primary GSM matrix using bracket counts (21.2→20/21, 14.5→14/16).
2. Searches archive per pair; auto-selects 20×16 (closest GSM with sufficient data).
3. Ranks all 20×16 articles; highlights closest matches (e.g. 12000020BDKK).
4. Returns top 3 distinct constructions (deduped by fingerprint and article family).
5. Engineer may click 50×40 or another GSM row to switch dataset and refresh cards.
6. Export XML from primary (Best Match) article.
```

### 3.3 Example 2: Plain Weave (Selectable Pair)

```
Input: 45.6×43.6, 145×76, Plain, 100% Cotton, GSM 116
Primary pairs include 50×40 (GSM 119.1, 14 articles) and 45×45 (GSM 122, auto-selected when best GSM fit).
User clicks 50×40 → recommendations refresh to 50×40 dataset without re-submitting the form.
```

## 4. Input/Output Contract

### 4.1 Input Model (User-Supplied)

| Details                                                         |
| --------------------------------------------------------------- |
| Input Field Type Required Notes                                 |
| Warp Count Numeric Yes Yarn count for warp direction            |
| Weft Count Numeric Yes Yarn count for weft direction            |
| Finish EPI Numeric Yes Target finish ends per inch              |
| Finish PPI Numeric Yes Target finish picks per inch             |
| Weave Categorical Yes e.g., Plain, Twill, Satin                 |
| Blend Categorical Yes Fiber blend descriptor                    |
| GSM Numeric Optional Used as similarity constraint if available |

### 4.2 Output Model (System-Generated)

```
The output contract aligns to the business-required 14-field construction set.
```

| Details                               |
| ------------------------------------- |
| Output Field Source                   |
| Warp Count Historical/ Formula output |
| Weft Count Historical/ Formula output |
| Reed Predicted                        |
| Ends/ Dent Predicted                  |
| Reed Space Predicted                  |
| Greige EPI Predicted                  |
| Greige PPI Predicted                  |
| Output Field Source                   |
| Finish EPI Predicted / reference      |
| Finish PPI Predicted / reference      |
| Target GSM Predicted / reference      |
| Finish Width Predicted                |
| Blend Ratio Predicted / reference     |
| Loom Type Predicted / reference       |
| Cover Factor Predicted                |

## 5. Intelligence Engine (Detailed)

### 5.1 Historical Intelligence Track (v2.2)

```
The historical engine follows the client feasibility process:
```

```
1. GSM back-calculation → warp×weft count-pair matrix (primary + expanded).
2. Per count pair: 5-case cascade search on the archive subset.
3. Auto-select active pair (GSM-closest with sufficient matches); user may override.
4. Rank articles with weighted absolute-delta scoring on finish EPI/PPI/GSM.
5. Return top 2–3 exact historical articles (no median or scenario synthesis).
```

#### 5.1.0 GSM Count-Pair Matrix

**Formula:**

```
GSM = ((Finish_EPI / Warp_Count) + (Finish_PPI / Weft_Count)) × 24.5
```

**Primary count brackets** (`primary_standard_counts`):

| Input example | Bracket counts | Rationale |
| ------------- | -------------- | --------- |
| 20.3 warp | 20, 21 | Low-count tight spacing at 20–21 band |
| 14.5 weft | 14, 16 | Span rule when input sits in lower quarter of interval |
| 30.02 warp | 30, 32 | Two nearest standard Ne counts |
| 32.3 weft | 30, 32 | Two nearest standard Ne counts |
| 45.6 warp | 40, 50 | Coarse-count band rule (40 ≤ value < 48) |
| 55.6 warp | 50, 60 | Two nearest standard Ne counts |

Primary cases are ordered **client spreadsheet order** (warp ascending, weft ascending on first warp then descending on second warp for 30s; low-count pairs use warp descending with weft ascending), not sorted by GSM delta.

**Finish-spec refinement (single pass after active pair):** After count-pair search and auto/user selection, `refine_finish_specs()` runs **once** on merged archive rows (preview + ranked matches) using **active-pair** warp/weft counts. PPI evaluation uses **minimum GSM delta across all four primary count pairs**; EPI down runs only when PPI was not adjusted and archive cluster is ≥4 Ne below user input without worsening primary-pair GSM fit. User raw finish EPI/PPI remain in `input`; unified adjusted values are in `refined_finish_specs` (no separate `ai_finish_*` fields). GSM cases are recomputed with these specs after refinement.

| Policy | When applied | Example |
| ------ | ------------ | ------- |
| PPI up | Archive finish-EPI band has higher PPI (≤15%) improving min GSM delta across primary pairs by >0.5 | Ex. 4: 86→96 |
| EPI down | Archive cluster ≥4 Ne below user finish EPI; improves min GSM delta across primary pairs | Ex. 3: 132→126 |
| No change | No archive band improvement or PPI already adjusted | Ex. 1–2, Ex. 5 |

**Auto-select tie-break:** Among primary cases with sufficient archive rows and GSM within tolerance of the best delta, pick **minimum `gsm_delta`**, then higher `match_count`, then spreadsheet order (`sr`).

GSM cases use **refined** finish EPI/PPI. AI suggestion consumes the **same** refined specs (no second refinement pass).

**Expansion:** If no pair yields ≥3 rankable rows, expand using `nearest_standard_counts()` up to 6 levels until a viable pair is found or max expansion is reached.

Each case row includes: `sr`, `warp_count`, `weft_count`, `gsm`, `gsm_delta`, `match_count`, `status` (`no_data` | `insufficient` | `searched` | `selected`), `is_primary`, `expansion_tier`.

#### 5.1.1 Cascade Search (5+1 Cases) — Per Count Pair

Applied **inside each count-pair archive subset** (not globally). Same case table as v2.1:

| Case | Count Filter | Weave Filter | Blend Filter | Description |
|---|---|---|---|---|
| Case-1 | Exact (±5 tolerance) | Exact weave | Exact blend | Strictest match |
| Case-2 | Exact (±5 tolerance) | Similar weave family | Exact blend | Count+blend fixed, weave relaxed |
| Case-3 | Similar (±12 tolerance) | Exact weave | Exact blend | Weave+blend fixed, count relaxed |
| Case-4 | Exact (±5 tolerance) | Exact weave | Similar blend family + dominant fiber ±15% | Count+weave fixed, blend relaxed |
| Case-5 | Similar (±12 tolerance) | Similar weave family | Similar blend family + ±15% fiber filter | All dimensions relaxed |
| Fallback | None | None | None | Full count-pair subset |

Minimum **3 rankable rows** (finish specs + greige EPI/PPI present) to activate a case.

#### 5.1.2 EPI/PPI Range Label (Display Only)

v2.2 **does not** pre-filter articles by finish EPI/PPI percentage bands before ranking. The range label is metadata for the UI:

```
EPI (target−5)–(target+5) / PPI (target−5)–(target+5)
```

Example: target 125×60 → `EPI 120-130 / PPI 55-65`.

> v2.1 EPI/PPI range probing (±5%…±50% row filtering) is **retired** in the prediction engine. Proximity to target EPI/PPI/GSM is handled in article scoring.

#### 5.1.3 Article Score Formula (Absolute Delta)

Used **only in the article-ranking phase**. Count similarity is already enforced by count-pair filtering; count weight is **not** applied here.

```
score = w_epi × |target_epi − row_epi|
      + w_ppi × |target_ppi − row_ppi|
      + w_gsm × |target_gsm − row_gsm|   (or penalty if GSM missing)

Default weights (user-tunable via UI sliders):
  epi_ppi = 35%  (split 17.5% finish_epi + 17.5% finish_ppi)
  gsm     = 25%
  count   = 40%  (reserved; not used in article ranking)

Lower score = better match.
```

#### 5.1.4 Deduplication Before Top-N

1. **Construction fingerprint** — same greige/finish EPI/PPI/GSM/reed/ends-dent → keep best score.
2. **Article family** — same numeric prefix (e.g. `12000072`) → one representative per family in top 3.

#### 5.1.5 Recommendation Model (Exact Articles)

v2.2 returns **2–3 distinct historical articles**, each with full construction fields copied from the archive row:

| Rank | Label | Usage |
| ---- | ----- | ----- |
| 1 | Best Match / Recommended | Primary offer to customer; XML export source |
| 2–3 | Alternative 1–2 | Additional distinct constructions from same dataset |

**Removed in v2.2:** distance-weighted average, weighted mode aggregation, optimistic/expected/pessimistic scenario bands, `formula_based` in prediction response.

#### 5.1.6 User-Selectable Count Pairs

After initial prediction, the user may click any GSM table row. The client re-posts to `/api/predictions/construction` with:

```json
{ "selected_warp_count": 50, "selected_weft_count": 40 }
```

The engine re-runs cascade + ranking for that pair, updates `active_count_pair`, `matches`, `dataset_articles`, and `reference_articles` without recomputing the full expansion search from scratch.

Response flag: `user_selected_pair: true` when override is active.

#### 5.1.7 Full Dataset Table

`dataset_articles` returns **all** scored articles for the active count pair, sorted by score. Rows matching top-3 construction fingerprints are marked `recommended: true` (green highlight in UI).

#### 5.1.8 Data Normalization (Preprocessing)

**Blend normalization:**
- Strip all spaces, underscores, and dashes: `65% PES / 35% CO` → `65%PES35%CO`
- `PER` → `%` (word boundary): `50PERCENT COTTON` → `50%CO`
- `COTTON` → `CO`: `100%COTTON` → `100%CO`
- `POLYESTER` → `PES`: `65%POLYESTER35%CO` → `65%PES35%CO`
- Result: 1,284 unique normalized blends (down from 1,287+ raw)

**Weave normalization:**
- Commas → spaces: `2/2, TWILL` → `2/2  TWILL`
- `TWL` → `TWILL`: `2/1 TWL` → `2/1 TWILL`
- Add missing "S" direction to twill patterns: `2/1 TWILL` → `2/1 S TWILL`
- Result: unified values like `2/1 S TWILL` (1,200 rows), `3/1 S TWILL` (1,427 rows)

**Garbage row filtering:**
- Rows containing "model" or "intput" in raw blend text are removed (template placeholders).

**Zero-value cleanup:**
- `FINISH EPI`, `FINISH PPI`, `FINISH GSM`, `FINISH WIDTH`, `Reed space`, `Greige Width in INCH`, `ON LOOM EPI`, `ON LOOM PPI` values of 0 are converted to NaN (treated as missing data).

> **Retired (v2.1):** Distance-weighted average recommendation, scenario bands (optimistic/expected/pessimistic), and percentage-based row scoring before article rank. See revision history.

#### 5.1.9 AI Construction Suggestion (v2.3 — Additive)

Returned as `ai_suggestion` in `/api/predictions/construction`. **Does not replace** exact-match `matches` or `recommendation`.

**Purpose:** Mirror the client spreadsheet “AI Suggestion” block — a **synthesized** construction tuned to finish targets, informed by the active count pair and archive articles in the current dataset.

**Inputs:** user finish EPI/PPI, target GSM, active count pair (warp×weft), top archive matches, full dataset (reed frequency).

**Algorithm (summary):**

1. Accept unified `refined_finish_specs` from predict (same values as GSM matrix).
2. Learn warp/weft shrinkage and draw-in ratios from weighted archive articles.
3. Compute formula on-loom target: `finish_epi × (1 − warp_shrink) × (1 − draw_in)`; override with archive on-loom median only when cluster IQR &lt; 4 and within 4 ends of formula target.
4. Evaluate Stockport reed candidates from archive matches plus formula-derived reeds when archive options are &gt;4 ends from target.
5. Pick reed minimizing `|onloom_epi − target_onloom|` among valid shrinkage bands; ends-per-dent preference 4/3 before 2.
6. Return construction + `derivation.steps` explaining parameter adjustments.

**Reed list:** Client standard counts 32–140 (`VARDHMAN_REED_COUNTS`); ends-per-dent preference 3 or 4 before 2.

**Stockport reed convention:** Onloom EPI = (Reed / 2) × Ends per dent. Greige EPI = Onloom × (1 + draw-in). Finish EPI = Greige / (1 − warp shrinkage).

**Golden validation:** [`PDC data/Examples .xlsx`](Examples%20.xlsx) — all **eight** client examples parsed in `backend/tests/fixtures/client_examples.py`; spreadsheet-archive tests in `backend/tests/test_ai_suggestion.py`; live `predict()` pipeline tests in `backend/tests/test_golden_examples_e2e.py`.

### 5.2 Formula Intelligence Track (Reference + AI Suggestion)

```
Shrinkage-reversal and Stockport reed formulas power the v2.3 ai_suggestion block.
They are NOT merged into exact-match recommendations (matches remain unchanged from v2.2).
```

#### 5.2.1 Core Engineering Formulas Used

```
1. Shrinkage Reversal
```

```
Greige_EPI = Finish_EPI / (1 - Warp_Shrinkage)
Greige_PPI = Finish_PPI / (1 - Weft_Shrinkage)
```

```
2. Reed-Density Relationship
```

```
Greige_EPI ≈ Reed_Count × Ends_per_Dent
```

```
3. Cover Factor
```

```
Cover_Factor = EPI × sqrt(Count)
```

```
4. Width Conversion Approximation
```

```
Greige_Width ≈ Reed_Space × 0.
Finish_Width ≈ Reed_Space × 0.
```

### 5.3 Reverse-Engineered Pattern Findings (Where Confidence is High)

```
The following findings are based on direct analysis of available historical data and are included because evidence is
strong:
```

| Details                                                         |
| --------------------------------------------------------------- |
| Finding Observed Value Confidence                               |
| Total historical rows analyzed 11,174 High                      |
| Working dataset rows 9,352 High                                 |
| Piece Dyed dataset rows 1,822 High                              |
| Correlation: (Reed × Ends/ Dent) vs Greige EPI 0.998 Very High |
| Dominant Ends/ Dent values 4, 3, 2 High                         |
| Width shrink (Reed Space to Finish Width, normalized)           |
| ~19% median (piece- dyed)                                       |
| Medium-                                                         |
| High                                                            |

### 5.4 Weave-Specific Shrinkage Lookup (Current Config)

```
Note: This table is the current formula intelligence lookup used by the service and may be revised as new
validated data accumulates.
```

| Details                                 |
| --------------------------------------- |
| Weave Key Warp Shrinkage Weft Shrinkage |
| 2/2 TWILL 0.18 0.                       |
| 2/2 S TWILL 0.18 0.                     |
| 2/2 Z TWILL 0.18 0.                     |
| 3/1 TWILL 0.15 0.                       |
| 3/1 S TWILL 0.15 0.                     |
| 3/1,Z TWILL 0.15 0.                     |
| 2/1 TWILL 0.12 0.                       |
| 2/1 S TWILL 0.09 0.                     |
| 2/1,Z TWILL 0.07 0.                     |
| 4/1 SATIN 0.26 0.                       |
| PLAIN 0.15 0.                           |
| RIBSTOP 0.18 0.                         |
| DEFAULT 0.15 0.                         |

### 5.5 Comparative Analysis Output

```
For each prediction request, the system can expose two tracks:
```

```
Historical Recommendation (recommendation, statistics)
Formula-Based Recommendation (formula_based)
```

```
This supports engineer-side verification before operational release.
```

```
Historical: based on similar executed articles
Formula: based on weave physics assumptions
```

```
Engineer decision = compare both + confidence + nearest references
```

## 6. Confidence, Risk, and Failure Modes

### 6.1 Confidence Levels (v2.2)

```
Confidence is determined from archive match depth and best-article score:
```

| Confidence | Criteria |
| ---------- | -------- |
| high | match_count ≥ 10 and best_score ≤ 10 |
| medium | match_count ≥ 5 and best_score ≤ 20 |
| low | match_count ≥ 3 (CASE_MIN_ROWS) |
| very_low | otherwise |

> v2.1 CV-based thresholds (match_count ≥ 60 and CV ≤ 20, etc.) are **retired** for the prediction engine. CV may still appear in analytics endpoints.

### 6.2 What Happens if a Wrong Pattern Enters History?

```
If one incorrect construction is recorded and reused without comparative validation:
```

```
Similar upcoming orders may receive biased historical recommendations.
Error can propagate across consecutive orders sharing weave/blend/count profile.
Confidence may remain deceptively high if sample volume is large but biased.
```

```
Mitigations required:
```

```
Enforce comparative review (historical vs formula) for medium/low confidence cases.
Flag outlier recommendations outside formula tolerance bands.
Maintain periodic validation against known successful outcomes.
```

### 6.3 Scenarios Where Calculations Can Break

| Details                                                   |
| --------------------------------------------------------- |
| Scenario Historical Track Formula Track Expected Behavior |
| Missing                                                   |
| weave/blend Cannot proceed Can default                    |
| Return validation error for                               |
| mandatory fields                                          |
| Sparse historical                                         |
| data Weak confidence Still available                      |
| Use fallback + mark low                                   |
| confidence                                                |
| Unknown weave                                             |
| type                                                      |
| Historical may                                            |
| still match                                               |
| Uses DEFAULT                                              |
| shrinkage Return with caution tag                         |
| Bad width units in                                        |
| source data                                               |
| Can distort width                                         |
| medians                                                   |
| Formula unaffected if                                     |
| inputs clean                                              |
| Unit normalization checks                                 |
| needed                                                    |
| Extreme custom                                            |
| finishes                                                  |
| Historical may be                                         |
| noisy Formula may underfit Require engineer review        |

## 7. XML Export Capability

### 7.1 Objective

```
The XML feature is designed to eliminate manual re-entry of construction parameters by exporting a structured
construction.xml artifact directly from prediction output.
```

### 7.2 Export Workflow

```
Predict Construction
↓
Review recommendation + formula comparison
↓
Click "Export to Penelope XML"
↓
Download construction.xml
↓
Use as import-ready technical sheet input
```

### 7.3 Construction Field-to-XML Mapping

| Details                                                                             |
| ----------------------------------------------------------------------------------- |
| Business                                                                            |
| Field XML Node/ Attribute Mapping Notes                                             |
| Weave Fabric/Weave@Name TechnicalData/Comment@Weave and Taken from prediction input |
| Blend Technical Data/Composition@Warp/@Weft/@Total Taken from prediction input      |
| Warp Count Yarns/ Yarn(0)/Count Derived fromrecommendation                          |
| Weft Count Yarns/ Yarn(1)/Count Derived fromrecommendation                          |
| Reed Count Technical Data/ReedDensity@Value Derived fromrecommendation              |
| Ends per                                                                            |
| Dent                                                                                |
| Technical Data/EndsPerDent@Back and Denting                                         |
| block                                                                               |
| Derived from                                                                        |
| recommendation                                                                      |
| Reed Space Technical Data/ReedWidth@Value Derived fromrecommendation                |
| Greige EPI Technical Data/WovenWarpDensity@Value Derived fromrecommendation         |
| Greige PPI Technical Data/WeftDensity@Value Derived fromrecommendation              |
| Finish EPI Technical Data/FinishedWarpDensity@Value Derived fromrecommendation      |
| Finish PPI Technical Data/FinishedWeftDensity@Value Derived fromrecommendation      |
| Finish Width Technical Data/FinishedWidth@Value Derived fromrecommendation          |

```
Export behavior:
```

```
Filename: construction.xml
Content type: application/xml
Encoding: UTF-8 with XML declaration
```

## 8. API Specification (Detailed)

### 8.1 Active Endpoints

| Details                                                         |
| --------------------------------------------------------------- |
| Endpoint Method Purpose                                         |
| /api/health GET Service and data health                         |
| /api/dashboard GET Summary metrics for datasets                 |
| /api/filters GET Filter values for weave/blend/loom             |
| /api/articles GET Search + paginated historical articles        |
| /api/analytics/relativity GET Dashboard relativity view         |
| /api/predictions/construction POST Main construction prediction |
| /api/predictions/export-xml POST XML export endpoint            |
| /api/validation/report GET Validation summary                   |

### 8.2 Prediction Request Schema (Logical)

```json
{
  "warp_count": 21.2,
  "weft_count": 14.5,
  "finish_epi": 125,
  "finish_ppi": 60,
  "weave": "3/1 S TWILL",
  "blend": "100%CO",
  "target_gsm": 235,
  "dataset": "all",
  "loom_type": "",
  "weights": {
    "count": 40,
    "epi_ppi": 35,
    "gsm": 25
  },
  "selected_warp_count": 50,
  "selected_weft_count": 40
}
```

`selected_warp_count` / `selected_weft_count` are **optional**. When present, the engine uses that count pair instead of the auto-selected pair (GSM table row click).

### 8.3 Prediction Response Highlights (v2.2)

```json
{
  "input": { "raw_warp_count": 21.2, "target_gsm": 235, "...": "..." },
  "count_cases": [
    { "sr": 1, "warp_count": 21, "weft_count": 14, "gsm": 250.8, "status": "no_data", "is_primary": true }
  ],
  "primary_count_cases": ["..."],
  "expanded_count_cases": ["..."],
  "active_count_pair": {
    "warp_count": 20, "weft_count": 16, "gsm": 245.0,
    "cascade_case": "Case-1: Exact Count + Exact Weave + Exact Blend",
    "range": "EPI 120-130 / PPI 55-65",
    "matches_found": 39,
    "user_selected": false
  },
  "user_selected_pair": false,
  "search_path": {
    "active_case": "Case-1: Exact Count + Exact Weave + Exact Blend",
    "search_instructions": "Search: 20COM×16COM, EPI(120-130)×PPI(55-65), ..."
  },
  "matches": [
    {
      "rank": 1,
      "master_article": "12000020BDKK",
      "score": 131.97,
      "construction": { "greige_epi": 114, "finish_gsm": 234, "...": "..." }
    }
  ],
  "dataset_articles": [
    { "master_article": "12000020BDKK", "score": 131.97, "recommended": true, "construction": {} }
  ],
  "recommendation": { "greige_epi": 114, "...": "primary match construction" },
  "reed_recommendation": { "...": "reed alternatives" },
  "data_quality": {
    "matching_source": "Case-1: Exact Count + Exact Weave + Exact Blend",
    "matches_analyzed": 3,
    "confidence": "low"
  },
  "reference_articles": [{ "master_article": "12000020BDKK", "_score": 131.97, "...": "..." }],
  "gsm_analysis": { "count_cases": ["..."], "target_gsm": 235 }
}
```

**Removed from response (v2.1):** `scenarios`, `statistics`, `formula_based`, `coefficient_of_variation`.

## 9. Frontend Functional Modules

### 9.1 Dashboard

```
System health and dataset volume
Top weave/blend distribution
Validation snapshot indicators
```

### 9.2 Prediction Studio (v2.2)

```
7-input construction request form (warp, weft, finish EPI/PPI, weave, blend, target GSM, dataset)
Weightage tune panel with relative sliders (Count/EPI-PPI/GSM) and lock/unlock per slider
GSM Calculation table — primary 4 cases + expandable additional cases; rows are clickable
Full archive dataset table for active count pair (green = recommended)
Best Match + Alternative construction cards (exact historical articles, not aggregated medians)
Reed × Ends/Dent alternatives panel
Match summary table (top 3)
XML export from primary match
```

**Interaction:** Clicking a GSM row re-fetches predictions with `selected_warp_count` / `selected_weft_count` without re-submitting the form.

### 9.3 Article Archive

```
Fuzzy search across article identifiers/weave/blend
Pagination and filter controls
```

### 9.4 Documentation Tab

```
Formula and field explanation for non-textile and textile users
Term-level tooltips with simplified definitions
```

## 10. Validation and Quality Framework

### 10.1 Validation Objective

```
Quantify how predicted greige fields align with known historical outcomes on sampled records.
```

### 10.2 Validation Endpoint

```
Endpoint: /api/validation/report
Inputs: sample size, random seed
Outputs: aggregate error behavior + confidence distribution
```

### 10.3 Recommended KPI Set

| Details                                                  |
| -------------------------------------------------------- |
| KPI Meaning                                              |
| MAE (Greige EPI) Absolute prediction error in EPI        |
| MAE (Greige PPI) Absolute prediction error in PPI        |
| Confidence Mix % predictions by high/medium/low/very-low |
| Match Depth | Articles in active count-pair dataset used for ranking |

### 10.4 Unit Test Suite (v2.2)

```bash
cd backend && .venv/bin/python -m pytest -q
```

Current baseline: **44 passed**, including:

- GSM count-pair matrix (Example 1: 21×14, 21×16, 20×14, 20×16)
- `primary_standard_counts` bracket logic (21.2→20/21, 45.6→40/50)
- Exact-match ranking (`12000020BDKK` top match for Example 1)
- Construction fingerprint + article-family deduplication
- User-selected count pair (`selected_warp_count` / `selected_weft_count`)
- No median aggregation on primary match construction fields

## 11. Non-Functional Requirements

### 11.1 Performance

```
Prediction API should respond in interactive range for engineering workflow.
Data-loading logic should avoid repeated heavy I/O in steady-state usage.
```

### 11.2 Reliability

```
API must provide clear error responses for missing mandatory inputs.
XML export must produce valid UTF-8 XML for every successful prediction.
```

### 11.3 Explainability

```
Every prediction should include match source and confidence.
Comparative formula output should remain visible to users for sanity-checking.
```

### 11.4 Maintainability

```
Weave shrinkage table should be versioned and auditable.
Formula functions should be modular for future calibration.
```

## 12. Security, Governance, and Change Control

### 12.1 Data Governance

```
Construction intelligence is only as strong as source data quality.
Input dataset revisions must be traceable (source date + owner).
```

### 12.2 Recommendation Governance

```
Medium/low-confidence predictions should be engineer-reviewed before release.
Outlier guardrails should be introduced for automated approvals.
```

### 12.3 Versioning

```
Prediction logic version and shrinkage table version should be logged with each release.
```

## 13. AI Strategy for PDC Use Case

### 13.1 AI Positioning (Current Phase)

```
The current platform uses AI-assisted statistical intelligence :
```

```
Learns nearest relevant historical examples.
Applies weighted similarity rather than static lookup.
Produces confidence-aware recommendations.
Exposes comparative tracks to reduce silent model risk.
```

```
This is not a black-box model deployment; it is explainable intelligence with deterministic components.
```

### 13.2 Why AI is Still Relevant Here

Even where formulas exist, textile production outcomes are influenced by practical variables not fully captured in
equations (route behavior, process variability, composition-specific handling, loom context).

```
Therefore, AI/statistical intelligence is used to:
```

```
Capture real-world behavior from executed production history.
Prioritize what actually worked for similar requirements.
Quantify confidence and uncertainty.
```

### 13.3 Target AI Maturity Path

```
Phase 1 (Current):
Historical similarity + deterministic formulas + confidence
```

```
Phase 2:
Adaptive weighting and drift-aware recalibration
```

```
Phase 3:
Multimodal inputs (vision + tabular + process telemetry)
```

## 14. Future Roadmap

### 14.1 Phase 2 (High-Level)

```
Image/PDF Input
↓
Scale Calibration (pixel-to-mm/inch)
↓
Texture + Directional Feature Extraction
↓
Warp/Weft Density Estimation
↓
Weave Pattern Classification
↓
Construction Candidate Generation
↓
Human Validation + Feedback Loop
```

### 14.2 Phase 3: Enterprise Integration

```
ERP/NOW live sync for up-to-date construction history.
Route-linked process intelligence (route-specific correction factors).
Governance workflows for recommendation approvals and audits.
```

## 15. Business Impact Analysis

### 15.1 Coverage and Scale

| Details                    |
| -------------------------- |
| Metric Value               |
| Working dataset rows 9,    |
| Piece Dyed dataset rows 1, |
| Total historical rows 11,  |

### 15.2 Core Analytical Strengths

| Details                                                  |
| -------------------------------------------------------- |
| Insight Observed                                         |
| Reed-Dent-EPI relationship Very strong (corr ~0.998)     |
| Historical fallback robustness 5-case cascade + fallback available |
| Comparative transparency Historical + formula output     |

### 15.3 Expected Operational Benefits

```
Reduced engineering turnaround time for construction planning.
Improved consistency across similar customer briefs.
Better traceability for why a construction was selected.
```

```
Lower manual re-entry risk via XML export workflow.
```

## 16. Glossary

| Details                                                                              |
| ------------------------------------------------------------------------------------ |
| Term Definition                                                                      |
| Article Historical construction record identifier                                    |
| Warp Count Yarn count along fabric length direction                                  |
| Weft Count Yarn count along width direction                                          |
| EPI Ends per inch                                                                    |
| PPI Picks per inch                                                                   |
| Greige Fabric state before finishing                                                 |
| Finish Fabric state after finishing operations                                       |
| Reed Count Dents per inch on reed                                                    |
| Ends per Dent Number of warp ends inserted per dent                                  |
| Reed Space Loom width reference in inches                                            |
| GSM Grams per square meter                                                           |
| Cover Factor Surface cover metric derived from density and count                     |
| Shrinkage Reversal Formula to infer greige from finish using shrink factors          |
| Matching Source Indicates whether exact, weave-fallback, or global-fallback was used |
| CV Coefficient of variation; stability indicator                                     |
| Confidence Reliability label derived from match depth and variation                  |
| Reference Articles Top nearest historical examples used in prediction                |

## 17. Acceptance Criteria

```
The platform is considered functionally compliant when:
```

```
1. 7-input prediction requests generate GSM cases and exact-match articles reliably.
2. 14-field construction output is visible per recommended article (not synthesized median).
3. GSM table allows user selection of count pair; recommendations refresh accordingly.
4. Full dataset table shows all archive rows for active pair with closest matches highlighted.
5. Historical recommendations include confidence, cascade case, and match source.
6. construction.xml export succeeds from primary (Best Match) article.
7. Article archive supports fuzzy search and filtering.
8. Validation endpoint returns error-quality indicators for sampling.
9. Backend test suite: 44+ tests including Example 1 golden cases (12000020BDKK, primary GSM matrix).
```

## 18. Conclusion

```
The PDC Intelligence Platform establishes a production-grade decision workflow for converting finish requirements into
greige construction recommendations with traceability, confidence, and export readiness.
```

```
By combining historical intelligence, formula intelligence, and XML operationalization, the system creates a scalable
foundation for Vardhman’s next-phase AI roadmap.
```

## 19. Locked Requirements vs Ad Hoc Requirements

```
This section classifies PDC requirements into two groups inspired by the Greige TRD style:
```

```
Locked Requirements : confirmed and already implemented in Phase 1.
Ad Hoc Requirements : proposal-stage extensions planned for Phase 2+ AI evolution.
```

### 19.1 Classification Framework

| Details                                                    |
| ---------------------------------------------------------- |
| Requirement Class Meaning Change Tolerance                 |
| Locked Stable baseline behavior required in production Low |
| Ad Hoc Planned capability under phased rollout Medium-High |

### 19.2 Locked Requirements (Phase 1 - Statistical Intelligence)

#### 19.2.1 Locked Inputs and Outputs

```
6-input interface (loom type removed from input, sourced from data).
14+ output construction response envelope with scenario bands.
Required weave/blend validation.
Tunable weightage sliders (Count/EPI-PPI/GSM) with lock/unlock per slider.
```

#### 19.2.2 Locked Decision Logic (v2.2)

```
GSM count-pair matrix with primary_standard_counts bracketing + dynamic expansion.
Per-pair 5-case cascade (count/weave/blend progressive relaxation).
Auto-select GSM-closest viable count pair; user override via selected_warp/weft.
Absolute-delta article scoring on finish EPI/PPI/GSM (count weight reserved, not used in rank).
Top 2–3 exact historical articles; dedupe by construction fingerprint and article family.
Confidence from match depth + best score (no CV in prediction path).
```

#### 19.2.3 Locked Operational Artifacts (v2.2)

```
GSM count-pair table (primary + expanded, selectable rows).
Full dataset_articles table with recommended highlights.
Exact-match construction cards (Best Match + Alternatives).
Reference summary table (top 3).
Reed alternatives panel.
XML export endpoint with construction.xml output.
```

### 19.3 Ad Hoc Requirements (Phase 2+ AI Expansion)

```
Ad Hoc requirements are non-breaking roadmap proposals and must be governed via validation before moving into
Locked scope.
```

| Details                                                                                       |
| --------------------------------------------------------------------------------------------- |
| Ad Hoc Theme Proposed Direction                                                               |
| Adaptive weighting Learn distance weights from outcomes                                       |
| Confidence calibration Convert static confidence thresholds into calibrated reliability bands |
| Drift handling Detect behavior drift by weave/blend/loom slices                               |
| Uncertainty intervals Return ranges, not only point estimates                                 |
| CV integration Bring image-derived candidate inputs into recommendation loop                  |

### 19.4 Promotion Criteria: Ad Hoc -> Locked

```
A planned feature is promoted from Ad Hoc to Locked only if:
```

```
1. Functional behavior is documented.
2. Validation evidence is reproducible.
3. Regression tests pass against locked baseline.
4. Domain sign-off confirms business utility.
```

## 20. AI Roadmap Blueprint for PDC (Proposal-Oriented)

```
This section provides the AI-forward plan without claiming unimplemented outcomes.
```

### 20.1 Phase Structure

| Details                                                                     |
| --------------------------------------------------------------------------- |
| Phase Intelligence Mode Status                                              |
| Phase 1 Statistical intelligence + formula comparison Implemented baseline  |
| Phase 2 Adaptive AI recommendations with calibration Planned                |
| Phase 3Multimodal intelligence (tabular + vision + process signals) Planned |

### 20.2 Phase 1 (Implemented): Statistical Intelligence

```
Phase 1 uses explainable decisioning:
```

```
historical retrieval,
weighted ranking,
robust central tendency,
confidence labeling,
formula-side comparative view.
```

```
This ensures immediate operational value while preserving explainability.
```

### 20.3 Phase 2 (Planned): AI Recommendation Layer

```
Phase 2 proposes AI-driven learning over Phase 1 outputs and outcomes:
```

```
Historical + Formula Outputs
↓
Outcome Tracking Layer
↓
Adaptive Weight Learning
↓
Confidence Recalibration
↓
AI Recommendation Layer
```

#### 20.3.1 Planned AI Capabilities

| Details                                                                             |
| ----------------------------------------------------------------------------------- |
| Capability Description                                                              |
| Learned Similarity                                                                  |
| Weights                                                                             |
| Replace static numeric weights with calibrated weights by                           |
| cohort                                                                              |
| Confidence Calibration Align confidence levels with observed post-approval behavior |
| Pattern Drift Alerts Detect construction behavior changes in recent windows         |
| Recommendation                                                                      |
| Intervals Return likely output ranges with confidence bounds                        |

#### 20.3.2 Planned AI Inputs

```
Phase 2 model candidates may use:
```

```
finish targets,
weave and blend,
count features,
cohort metadata (dataset/loom type),
historical delta patterns.
```

#### 20.3.3 Planned AI Outputs

```
recommended construction point estimates,
interval estimates,
explainability snippets,
reliability score.
```

### 20.4 Phase 3 (Planned): Vision-Assisted Intelligence

```
Phase 3 introduces image-derived candidate signals without replacing engineering governance.
```

```
Image/PDF -> CV Feature Extraction -> Candidate Construction ->
Historical + Formula + AI Fusion -> Engineer Review
```

#### 20.4.1 Planned CV Contributions

```
density hints (EPI/PPI candidates),
weave family classification,
repeat geometry hints.
```

#### 20.4.2 Governance Constraint

```
No autonomous final construction approval in initial CV rollout.
```

### 20.5 AI Explainability Policy

```
Any Phase 2+ AI layer should provide:
```

```
1. Feature influence summary.
2. Similar historical references used.
3. Confidence decomposition.
4. Divergence marker vs formula baseline.
```

### 20.6 AI Validation Policy (Proposal)

| Details                                                         |
| --------------------------------------------------------------- |
| Validation Dimension Intent                                     |
| Point Accuracy Check EPI/ PPI/Reed errors on holdout sets       |
| Stability Ensure model does not oscillate across similar inputs |
| Explainability Ensure recommendation rationale is inspectable   |
| Safety Ensure low-confidence recommendations are review-gated   |

### 20.7 AI Deployment Gates

```
Planned gate structure:
```

```
1. Offline validation gate.
2. Shadow-mode gate.
3. Controlled cohort rollout.
4. Full release gate with rollback path.
```

### 20.8 AI Risk Management (Proposal)

| Details                                                                                 |
| --------------------------------------------------------------------------------------- |
| AI Risk Planned Mitigation                                                              |
| Overfitting to noisy historical subsets Cohort-level regularization + robust validation |
| Confidence inflation Reliability calibration layer                                      |
| Drift under new process conditions Drift detector + periodic retraining                 |
| Black-box resistance Explainability as mandatory release criterion                      |

### 20.9 AI Program Governance Cadence (Proposal)

```
Weekly: review anomalies and comparative outliers.
Monthly: review drift and confidence calibration behavior.
```

```
Quarterly: review roadmap promotion from Ad Hoc to Locked.
```

### 20.10 AI Roadmap Non-Claims

```
To avoid hypothetical overstatement, this TRD intentionally does not claim:
```

```
deployed neural model performance,
production uplift percentages,
autonomous closure rates.
```

```
All AI roadmap elements above are framed as planned requirements, not implemented facts.
```

## 21. Formula Library (Engineering + Statistical)

### 21.1 Engineering Formula Set

#### 21.1.1 Shrinkage Reversal

```python
def calculate_greige_from_finish(finish_epi, finish_ppi, shrink_warp, shrink_weft):
    greige_epi = finish_epi / (1 - shrink_warp)
    greige_ppi = finish_ppi / (1 - shrink_weft)
    return greige_epi, greige_ppi
```

#### 21.1.2 Reed Relationship

```python
greige_epi_approx = reed_count * ends_per_dent
```

#### 21.1.3 Cover Factor

```python
cover_factor = epi * sqrt(count)
```

#### 21.1.4 Width Approximation

```python
greige_width = reed_space * 0.97
finish_width = reed_space * 0.80
```

### 21.2 Statistical Formula Set

#### 21.2.1 Article Score (Absolute Delta — v2.2)

```python
w_epi = weights.epi_ppi / 2
w_ppi = weights.epi_ppi / 2
w_gsm = weights.gsm

score = 0.0
if target_epi:  score += w_epi * abs(target_epi - row_epi or EPI_PPI_WINDOW)
if target_ppi:  score += w_ppi * abs(target_ppi - row_ppi or EPI_PPI_WINDOW)
if target_gsm:  score += w_gsm * abs(target_gsm - row_gsm or MISSING_GSM_PENALTY)
# count weights not applied — count pair already filters archive
```

#### 21.2.2 Output Model (Exact Articles)

```
Top 3 distinct articles after fingerprint + family deduplication.
No median, distance-weighted average, or scenario bands in v2.2 prediction path.
```

#### 21.2.3 Confidence Classification (v2.2)

```python
if match_count >= 10 and best_score <= 10:  confidence = "high"
elif match_count >= 5 and best_score <= 20: confidence = "medium"
elif match_count >= 3:                        confidence = "low"
else:                                         confidence = "very_low"
```

> **Retired:** Percentage-based distance score (21.2.1 v2.1), inverse-distance aggregation, CV-based confidence thresholds in prediction engine.

### 21.3 Hybrid Strategy Guidance

```
Recommended interpretation:
```

```
Historical recommendation = primary operational track.
Formula-based recommendation = engineering sanity-check track.
Divergence between two tracks should trigger engineer review.
```

## 22. Comparative Analysis Specification

### 22.1 Objective

```
Allow users to inspect what the construction would be from formula expectations versus what history recommends.
```

### 22.2 Comparative Metrics

| Details                                              |
| ---------------------------------------------------- |
| Metric Formula                                       |
| EPI Delta Hist Greige EPI - Formula Greige EPI       |
| PPI Delta Hist Greige PPI - Formula Greige PPI       |
| Reed Delta Hist Reed - Formula Reed                  |
| Metric Formula                                       |
| Width Delta Hist Finish Width - Formula Finish Width |

### 22.3 Suggested UI Block

```
Historical Recommendation Formula Recommendation Difference
-------------------------- ------------------------ ----------
Greige EPI: <hist_epi> Greige EPI: <formula_epi> <delta>
Greige PPI: <hist_ppi> Greige PPI: <formula_ppi> <delta>
Reed: <hist_reed> Reed: <formula_reed> <delta>
Ends/Dent: <hist_ed> Ends/Dent: <formula_ed> <delta>
```

### 22.4 Comparative Decision Rules

| Details                                                                  |
| ------------------------------------------------------------------------ |
| Condition Decision Aid                                                   |
| Delta small and confidence high Approve faster                           |
| Delta large and confidence low Mandatory engineer review                 |
| Delta large and confidence high Investigate formula table and data drift |

## 23. Deterministic Calculation Templates (Non-Hypothetical)

```
This section provides deterministic templates that come directly from locked formulas and process rules. It avoids
synthetic business outcomes.
```

### 23.1 Template A: Shrinkage Reversal

```
Given:
```

```
finish_epi
finish_ppi
warp_shrinkage from weave table
weft_shrinkage from weave table
```

```
Compute:
```

```
greige_epi = finish_epi / (1 - warp_shrinkage)
greige_ppi = finish_ppi / (1 - weft_shrinkage)
```

### 23.2 Template B: Reed and Ends/Dent Relationship

```
Given target greige_epi:
```

```
1. Evaluate standard ends/dent candidates in business-preferred order: 4, 3, 2, 5.
2. Compute reed = greige_epi / ends_per_dent.
3. Select candidate that falls in valid operational reed range.
```

### 23.3 Template C: Width Conversion

```
Given reed_space:
```

greige_width = reed_space * 0.97
finish_width = reed_space * 0.80

### 23.4 Template D: Cover Factor

```
Given epi and count:
```

cover_factor = epi * sqrt(count)

### 23.5 Template E: Historical Ranking

```
Given user payload and candidate rows:
```

```
1. Score each row with percentage-weighted similarity formula (no categorical penalties).
2. Sort ascending by score.
3. Select top N (up to 10 rows after EPI/PPI range probing).
4. Compute inverse-distance weights based on score distance from minimum.
5. Numeric fields: distance-weighted average from top matches.
6. Categorical fields: weighted mode (each row votes proportionally to closeness).
```

### 23.6 Template F: Confidence Assignment

```python
if match_count >= 60 and cv <= 20:
    confidence = "high"
elif match_count >= 20 and cv <= 35:
    confidence = "medium"
elif match_count >= 8:
    confidence = "low"
else:
    confidence = "very_low"
```

### 23.7 Template G: Comparative Delta Output

```
Compute per field:
```

```
epi_delta = historical.greige_epi - formula.greige_epi
ppi_delta = historical.greige_ppi - formula.greige_ppi
reed_delta = historical.reed - formula.reed
width_delta = historical.finish_width - formula.finish_width
```

### 23.8 Template H: XML Validation Checklist

```
For every export event:
```

```
1. Root node exists.
2. Fabric node exists.
3. TechnicalData node exists.
4. Exported file encoding is UTF-8.
5. File name is construction.xml.
```

### 23.9 Template I: Fallback Selection Order (Cascade)

```
Case-1: Exact Count + Exact Weave + Exact Blend
if < 3 rows ->
Case-2: Exact Count + Similar Weave + Exact Blend
if < 3 rows ->
Case-3: Similar Count + Exact Weave + Exact Blend
if < 3 rows ->
Case-4: Exact Count + Exact Weave + Similar Blend (±15% fiber proximity)
if < 3 rows ->
Case-5: Similar Count + Similar Weave + Similar Blend (±15% fiber proximity)
if < 3 rows ->
Fallback: Full dataset (no count/weave/blend filter)
```

After cascade case selection, EPI/PPI range probing narrows candidates within the case:
```
±5% → ±10% → ±15% → ±20% → ±25% → ±35% → ±50%
(Tries both dimensions together, then each independently with wider secondary)
```

### 23.10 Template J: EPI/PPI Range Probing (Post-Cascade)

```
Within the active cascade case, EPI/PPI range filter is applied automatically:
```

```
Tolerances: ±5% → ±10% → ±15% → ±20% → ±25% → ±35% → ±50%
```

```
At each tolerance, the probe tries in order:
  1. EPI + PPI together
  2. EPI alone (PPI relaxed fully, then widened)
  3. PPI alone (EPI relaxed fully, then widened)

Stops at the first tolerance achieving ≥ 3 rows.
Independent dimension relaxation avoids over-relaxing both when one suffices.
No separate pre-filter step — this replaces the old ±30% static bands.
```

### 23.11 Template K: Formula Eligibility Rule

```
Formula track requires:
```

```
finish EPI present
finish PPI present
```

```
If either missing, formula response returns structured error message.
```

### 23.12 Template L: Engineering Review Gate by Confidence

| Details                                             |
| --------------------------------------------------- |
| Confidence ConfidenceReview ModeReview Mode         |
| High Standard approval                              |
| Medium Comparative review required                  |
| Low Comparative + reference-depth review            |
| Very Low Manual engineering recommendation required |

## 24. Test Strategy and Quality Gates

### 24.1 Test Pyramid

```text
┌──────────────────────────┐
│ End-to-End API + UI      │
└─────────────┬────────────┘
              ↓
┌──────────────────────────┐
│ Integration Tests        │
└─────────────┬────────────┘
              ↓
┌──────────────────────────┐
│ Unit Tests (Formulas)    │
└──────────────────────────┘
```

### 24.2 Unit Test Coverage Targets

| Details                         |
| ------------------------------- |
| Component Minimum Coverage Goal |
| Text normalization 95%          |
| Numeric parsing 95%             |
| Distance scoring 90%            |
| Confidence logic 95%            |
| Formula functions 95%           |
| XML mapping 90%                 |

### 24.3 Functional Test Cases (Representative)

| Details                                                                 |
| ----------------------------------------------------------------------- |
| Case IDScenario Expected Result                                         |
| FT-001 Predict with all inputs Success + recommendation + formula_based |
| FT-002 Missing weave Error with required_fields                         |
| FT-003 Missing blend Error with required_fields                         |
| FT-004 Exact match tier matching_source = exact weave + blend           |
| FT-005 Weave fallback tier matching_source = weave fallback             |
| FT-006 Global fallback tier matching_source = global fallback           |
| FT-007 XML export success Valid UTF-8 XML download                      |
| Case IDScenario Expected Result                                         |
| FT-008 Archive fuzzy search Returns matched records                     |
| FT-009 Confidence high pathconfidence = high                            |
| FT-010 Confidence low path confidence = low/very_low                    |

### 24.4 XML Contract Tests

```
1. Root tag must be PenelopeDesigns.
2. Fabric node must exist.
3. TechnicalData node must exist.
4. Core mapped fields must be non-empty when source prediction field exists.
```

## 25. Operational SOP (Recommended)

### 25.1 Daily Operations

```
1. Validate health endpoint before start of shift.
2. Verify dataset load status and counts.
3. Use prediction studio for new development briefs.
4. Review comparative panel before final recommendation issue.
5. Export XML only after engineering sign-off.
```

### 25.2 Weekly Operations

```
1. Review low-confidence predictions.
2. Inspect large historical-vs-formula divergence cases.
3. Track archive updates and drift indicators.
```

### 25.3 Monthly Operations

```
1. Reassess shrinkage lookup entries with latest completed orders.
2. Re-run validation report with stable sample size.
3. Produce performance memo for engineering leadership.
```

## 26. Governance and Change Management

### 26.1 Model/Logic Change Protocol

```
Any update to scoring weights, shrinkage lookup, or formula constants should include:
```

```
1. Change proposal note.
```

```
2. Expected impact summary.
3. Validation evidence.
4. Rollback plan.
```

### 26.2 XML Mapping Change Protocol

```
Any XML field mapping change requires:
```

```
1. Mapping diff table.
2. Sample before/after XML.
3. Engineering sign-off.
```

### 26.3 Audit Trail Minimum

```
Capture for every prediction event:
```

```
timestamp
input payload hash
matching source
confidence
recommendation snapshot
formula snapshot
```

## 27. Expanded AI Strategy for PDC

### 27.1 Why AI-Labeled Intelligence is Correct for This System

```
This platform performs AI-style decisioning via pattern recognition, similarity weighting, fallback logic, uncertainty
classification, and recommendation generation from large historical evidence. While no deep neural model is currently
deployed, the decision behavior is still intelligence-driven and adaptive to data.
```

### 27.2 Current AI Pattern Classes

| Details                      |
| ---------------------------- |
| Pattern Class Used Today     |
| Similarity Search Yes        |
| Heuristic Weighting Yes      |
| Rule + Formula Fusion Yes    |
| Confidence Estimation Yes    |
| Drift Monitoring Partial     |
| Active Learning Loop Planned |

### 27.3 Planned AI Maturity Stages

| Details                                                  |
| -------------------------------------------------------- |
| Stage Focus                                              |
| Stage Focus                                              |
| Stage 1 Historical + formula explainable intelligence    |
| Stage 2 Adaptive calibration by weave/blend/loom cohorts |
| Stage 3 Drift-aware online correction                    |
| Stage 4 Vision + tabular multimodal recommendation       |

### 27.4 PDC-Specific AI Research Directions

```
1. Weave-cluster-specific shrinkage learning.
2. Blend-sensitive correction factors.
3. Width-behavior modeling by loom family.
4. Confidence calibration from post-production outcomes.
5. Recommendation uncertainty bands instead of point estimates.
```

## 28. Computer Vision Phase (Extended but Scoped, subject to change)

### 28.1 Problem Statement

```
Current PDC workflow still requires manual estimation when only visual sample or swatch is available.
```

### 28.2 CV Target Capabilities

```
Automatic EPI/PPI extraction from calibrated images.
Weave family classification from texture signatures.
Repeat pattern estimation for checks/stripes/grids.
Candidate construction shortlist generation for engineer review.
```

### 28.3 CV Reference Flow

```
Sample Image/PDF
↓
Perspective Correction + Scale Calibration
↓
Directional Frequency Analysis
↓
Warp/Weft Density Estimation
↓
Weave Family Classification
↓
Construction Candidate Generation
↓
Engineer Confirm/Adjust
```

### 28.4 CV Integration with Existing Engine

```
CV outputs become soft-inputs into current prediction API.
Historical and formula tracks remain the decision core.
CV confidence should be displayed separately from construction confidence.
```

### 28.5 CV Non-Goals for Initial Rollout

```
No fully autonomous final construction approval.
No direct machine parameter issuance without engineer confirmation.
```

## 29. Implementation Roadmap and Milestones

### 29.1 Milestone Plan

| Details                                                    |
| ---------------------------------------------------------- |
| Milestone Scope Exit Criteria                              |
| M1 Core historical prediction Stable API + UI outputs      |
| M 2 XML export Downloadable valid XML                      |
| M 3 Formula comparison formula_based payload + UI block    |
| M 4 Comparative analytics Delta metrics and review logic   |
| M 5 Governance hardening SOP + audit + validation routines |
| M 6 CV pilot Controlled image-to-candidate flow            |

### 29.2 Delivery Checkpoints

```
1. Functional demo: prediction + references + confidence.
```

```
2. Functional demo: XML export with mapped fields.
3. Functional demo: comparative analysis panel.
4. Validation report review with engineering team.
```

## 30. Expanded Glossary (Detailed)

### 30.1 Textile and Construction Terms

| Details                                                        |
| -------------------------------------------------------------- |
| Term Definition                                                |
| Warp Lengthwise yarn direction                                 |
| Weft Widthwise yarn direction                                  |
| EPI Ends per inch                                              |
| PPI Picks per inch                                             |
| Reed A comb-like element controlling warp spacing              |
| Dent Slot in reed through which warp threads pass              |
| Reed Count Number of dents per inch                            |
| Ends per Dent Number of warp ends assigned to each dent        |
| Greige Unfinished woven fabric                                 |
| Finish Post-processed fabric                                   |
| GSM Grams per square meter                                     |
| Blend Ratio Fiber composition ratio                            |
| Loom Type Equipment/process category                           |
| Cover Factor Indicator of yarn cover density                   |
| Width Shrinkage Width reduction through processing             |
| Warp Shrinkage Warp-direction density change through finishing |
| Weft Shrinkage Weft-direction density change through finishing |
| Count Band Grouping by yarn count threshold                    |

### 30.2 Intelligence and Data Terms

| Details                                                             |
| ------------------------------------------------------------------- |
| Term Definition                                                     |
| Exact Match Same weave and blend cohort                             |
| Weave Fallback Weave-only cohort when exact is sparse               |
| Global Fallback Full dataset fallback                               |
| Distance Score Weighted similarity metric                           |
| Median Recommendation Central value from top references             |
| P 25/P75 Lower/upper quartile bounds                                |
| IQR Interquartile range                                             |
| CV Coefficient of variation                                         |
| Confidence Reliability label from sample depth + CV                 |
| Formula Track Deterministic engineering calculation output          |
| Historical Track Data-driven nearest-neighbor output                |
| Comparative Delta Difference between historical and formula outputs |

### 30.3 XML and Integration Terms

| Details                                                     |
| ----------------------------------------------------------- |
| Term Definition                                             |
| XML Export Structured machine-readable file output          |
| Root Node Top-level XML element                             |
| Technical Data XML block containing engineering fields      |
| Content-Disposition Header controlling filename on download |
| UTF-8 Character encoding standard                           |

## 31. Extended Acceptance Matrix

| Details                                                             |
| ------------------------------------------------------------------- |
| Requirement IDRequirement Verification Method                       |
| AC-001 System accepts required inputs API functional test           |
| AC-002 14 output fields available Response schema test              |
| AC-003 Matching source is returned Response assertion               |
| AC-004 Confidence is returned Response assertion                    |
| AC-005 Reference neighbors included Response assertion              |
| AC-006 Formula track included Response assertion                    |
| AC-007 XML endpoint returns valid XML XML parser validation         |
| AC-008 XML filename is construction.xml Header assertion            |
| AC-009 Archive fuzzy search works API search test                   |
| AC-010 Dashboard loads summary metrics API + UI check               |
| AC-01 1 Fallback hierarchy triggers correctly Tiered test scenarios |
| AC-012 CV roadmap documented Document review                        |

## 32. Appendix A: Pseudocode (Prediction v2.2)

```python
def predict_construction(payload):
    validate_required(payload, ["weave", "blend", "warp_count", "weft_count",
                                "finish_epi", "finish_ppi"])

    df = load_dataset(payload.dataset)

    # Step 1: Build GSM count-pair cases (expand until viable pair)
    count_cases, active_pair, matches_df, meta = expand_and_search(
        df, payload.warp_count, payload.weft_count,
        payload.finish_epi, payload.finish_ppi, payload.target_gsm,
        payload.weave, payload.blend,
    )

    # Step 2: User override from GSM table click
    if payload.selected_warp_count and payload.selected_weft_count:
        active_pair, matches_df = activate_count_pair(
            df, count_cases,
            payload.selected_warp_count, payload.selected_weft_count, ...
        )

    # Step 3: Rank exact articles (no aggregation)
    matches, dataset_articles = rank_dataset(matches_df, target, payload.weights, top_n=3)

    recommendation = matches[0]["construction"] if matches else {}
    confidence = classify_confidence(len(matches_df), matches[0]["score"] if matches else 999)

    return {
        "count_cases": count_cases,
        "active_count_pair": active_pair,
        "user_selected_pair": bool(payload.selected_warp_count),
        "matches": matches,
        "dataset_articles": dataset_articles,
        "recommendation": recommendation,
        "reed_recommendation": recommend_reed(recommendation.greige_epi),
        "data_quality": {"confidence": confidence, "matching_source": active_pair.cascade_case},
        "reference_articles": matches,
    }
```

## 33. Appendix B: Pseudocode (XML Export)

```python
def export_xml(prediction):
    rec = prediction.recommendation
    inp = prediction.input

    root = Element("PenelopeDesigns", Version="v1.12")
    fabric = SubElement(root, "Fabric", Name="construction")

    # map yarns
    map_yarns(fabric, rec, inp)

    # map structural nodes
    map_weave_draft_denting(fabric, rec, inp)

    # map technical data
    map_technical_data(fabric, rec, inp)

    return xml_bytes(root, filename="construction.xml")
```

## 34. Appendix C: Engineering Review Checklist

```
Before approving any construction recommendation for downstream use:
```

```
1. Confirm matching source.
2. Confirm confidence tier.
3. Check nearest 3 historical references.
4. Compare historical vs formula outputs.
5. Validate reed and ends/dent relation sanity.
6. Validate width assumptions.
7. Approve and export XML.
```

## 35. Appendix D: Release Readiness Checklist

| Details                          |
| -------------------------------- |
| Item Status Requirement          |
| Backend API smoke tests Pass     |
| Item Status Requirement          |
| Prediction payload schema Stable |
| XML export validation Pass       |
| Frontend prediction flow Pass    |
| Comparative panel rendering Pass |
| Validation report endpoint Pass  |
| Documentation update Complete    |

## 36. Appendix E: Expanded API Behavior Matrix

| Details                                                                |
| ---------------------------------------------------------------------- |
| Endpoint Input State Output State                                      |
| /api/health Service up health object                                   |
| /api/dashboard Data loaded summary cards data                          |
| /api/filters Data loaded weave/blend/loom arrays                       |
| /api/articles page/limit/search paginated records                      |
| /api/predictions/constructionvalid payload recommendation + formula    |
| /api/predictions/constructionmissing weave/blend structured error      |
| /api/predictions/export-xml valid prediction object XML download bytes |
| /api/validation/report sample_size MAE + confidence aggregates         |

## 37. Appendix F: Extended Risk Register

| Details                                                                      |
| ---------------------------------------------------------------------------- |
| Risk IDRisk Impact Mitigation                                                |
| R-001 Poor data quality in source sheets High data quality checks + coercion |
| R-002 Unknown weave alias Mediumalias map + default shrinkage                |
| R-003 Confidence overestimation High periodic calibration                    |
| R-004 Formula drift due to process change High monthly shrinkage review      |
| R-005 XML consumer mismatch Mediummapping contract tests                     |
| R-006 Unit mismatch width cm/inch High explicit normalization checks         |
| R-007 Sparse data for niche blends Mediumfallback + manual review            |
| R-008 Outlier-heavy neighborhoods Mediumrobust statistics + filtering        |
| R-009 Regression in scoring weights Mediumversioned tuning + tests           |
| R-010 Frontend crash on null numeric fields Mediumnull guards + UI tests     |

## 38. AI Research Blueprint for PDC Use Case

```
This section provides a research-grade structure for introducing stronger AI behavior in a controlled and explainable
manner while preserving current production reliability.
```

### 38.1 Research Hypotheses

| Details                                                                                                      |
| ------------------------------------------------------------------------------------------------------------ |
| Hypothesis                                                                                                   |
| ID Statement Expected Benefit                                                                                |
| H-001 Weave-specific shrinkage factors can be learnedadaptively from rolling windows Better formulaalignment |
| H-002 Blend-aware correction factors reduce systematic EPI/PPI bias Improved predictionconsistency           |
| H-003 Route/loom stratification improves robustness for edgeconstructions Lower fallback error               |
| H-004 Historical-vs-formula deltas are predictive of executionrisk Better pre-approvalgovernance             |
| H-005 Confidence can be calibrated using post-productionoutcomes Better trustmanagement                      |

### 38.2 AI Candidate Approaches

| Details                                                |
| ------------------------------------------------------ |
| Approach Type Explainability Deployment Risk           |
| Quantile Regression Statistical ML High Low            |
| Gradient Boosted Trees Supervised MLMedium-High Medium |
| Bayesian Additive Models Probabilistic High Medium     |
| k NN Retrieval + Learned WeightsRetrieval AI High Low  |
| Neural Tabular Models Deep Learning Medium-Low High    |

### 38.3 Recommended Near-Term AI Strategy

```
1. Keep historical retrieval engine as primary source of truth.
2. Introduce learnable weighting over existing distance features.
3. Add uncertainty intervals for key outputs (Greige EPI/PPI/Reed).
4. Track post-approval outcomes and perform confidence calibration.
5. Avoid black-box end-to-end replacement in early phases.
```

### 38.4 AI Explainability Requirements

```
Any future AI model must expose:
```

```
Top feature contribution summary.
Similar reference constructions used for decision context.
Prediction interval (not only point estimate).
Confidence decomposition (data depth vs pattern stability).
```

### 38.5 AI Governance Requirements

| Details                                                        |
| -------------------------------------------------------------- |
| Governance Control Requirement                                 |
| Governance Control Requirement                                 |
| Model Versioning Every model/reweighing must be version-tagged |
| Feature Logging Input feature snapshots must be logged         |
| Drift Watch Data and output drift should be measured monthly   |
| Rollback Path Previous model should remain deployable          |
| Human Override Engineers can override with justification       |

## 39. Detailed Backend Specification

### 39.1 Service Initialization Contract

```
Backend initialization must ensure:
```

```
1. Working and Piece Dyed datasets are loadable.
2. Unioned column schema is stable.
3. Normalized columns are materialized.
4. Health endpoint reflects load status accurately.
```

### 39.2 Data Loading Flow

```
Read Working XLSX
↓
Read Piece Dyed XLSX
↓
Schema union and reindex
↓
Concatenate datasets
↓
Normalize text + parse numeric
↓
Derive utility columns (weave/blend/count band)
↓
Set service-ready dataframe
```

### 39.3 Parsing and Normalization Functions

| Details                                              |
| ---------------------------------------------------- |
| Function Purpose                                     |
| _clean_text Normalize textual values                 |
| _safe_float Numeric coercion with null-safe behavior |
| _extract_count Parse yarn count from code strings    |
| _normalize_weave Canonical weave formatting          |
| _normalize_blend Canonical blend formatting          |
| Function Purpose                                     |
| _count_band Count segmentation for filtering         |

### 39.4 Prediction Function Contract

```
predict_construction(payload) should:
```

```
1. Validate mandatory categorical and numeric fields.
2. Filter dataset by optional context (dataset/loom).
3. Build GSM count-pair matrix; expand search until viable pair found.
4. Run 5-case cascade per pair; auto-select active pair (or honor user selection).
5. Rank articles with absolute-delta scoring; dedupe; return top 3 exact matches.
6. Return count_cases, dataset_articles, matches, reed alternatives, confidence.
```

### 39.5 Validation Endpoint Contract

```
/api/validation/report should:
```

```
Sample valid rows.
Replay prediction pipeline on holdout rows.
Report aggregate error by key outputs.
Return confidence bucket distribution.
```

### 39.6 XML Export Function Contract

```
export_xml(payload) should:
```

```
1. Read prediction recommendation + input fields.
2. Construct XML hierarchy.
3. Map all available technical fields.
4. Return download response with filename.
```

## 40. Detailed Frontend Specification

### 40.1 Frontend Architectural Roles

| Details                                             |
| --------------------------------------------------- |
| Layer Role                                          |
| UI Components Render forms/cards/tables/tooltips    |
| State Layer Hold dashboard/prediction/archive state |
| API Layer Axios calls to backend endpoints          |
| Action Layer Trigger prediction and XML download    |

### 40.2 Prediction Studio UX Specification

#### 40.2.1 Form Interaction Rules

```
1. Weave and Blend must be selected before enabling prediction button.
2. Numeric fields should allow blank values (optional path).
3. Tooltip icons should be available for all technical labels.
```

#### 40.2.2 Result Display Rules

| Details                                                             |
| ------------------------------------------------------------------- |
| Rule ID Rule                                                        |
| UI-R-001 | Show Best Match card with distinct Alternatives (max 3) |
| UI-R-002 | Null-safe formatting for all numeric metrics |
| UI-R-003 | Show confidence, cascade case, and active count pair in header |
| UI-R-004 | GSM table rows clickable; selected row highlighted amber |
| UI-R-005 | Dataset table scrollable; recommended rows green |
| UI-R-006 | Loom displays "-" when missing in archive row |

#### 40.2.3 Comparative Block UX

```
Comparative block should include:
```

```
Formula Greige EPI
Formula Greige PPI
Formula Reed
Formula Ends/Dent
```

```
Future enhancement recommended:
```

```
Historical-vs-formula delta visualization.
Color coding for divergence bands.
```

### 40.3 XML Export UX Specification

| Details                                       |
| --------------------------------------------- |
| Step UX Behavior                              |
| 1 User clicks Export button                   |
| 2 POST request to /api/predictions/export-xml |
| 3 Browser receives blob response              |
| 4 Auto-downloads as construction.xml          |
| 5 Error alert shown on failure                |

## 41. Data Quality and Observability Framework

### 41.1 Data Quality Checks (Recommended)

| Details                                                              |
| -------------------------------------------------------------------- |
| Check IDCheck IDCheck Description Check Description SeveritySeverity |
| DQ-001 Missing weave ratio > threshold High                          |
| DQ-002 Missing blend ratio > threshold High                          |
| DQ-003 Non-numeric EPI/ PPI ratio Medium                             |
| DQ-004 Invalid reed*dent vs EPI consistency High                     |
| DQ-005 Width unit anomaly detection High                             |
| DQ-006 Extreme GSM outlier concentration Medium                      |

### 41.2 Observability Signals

| Details                                         |
| ----------------------------------------------- |
| Signal Source                                   |
| API latency endpoint-level timing               |
| Prediction throughput request counts            |
| Error rate endpoint errors                      |
| Confidence mix prediction responses             |
| Fallback distribution matching source counts    |
| XML export success rateexport endpoint outcomes |

### 41.3 Drift Monitoring Plan

```
Track monthly drift for:
```

```
weave distribution
blend distribution
finish EPI/PPI bands
average distance scores
confidence bucket shifts
formula-vs-historical delta distribution
```

### 41.4 Alerting Threshold Suggestions

| Details                                                  |
| -------------------------------------------------------- |
| Alert Threshold                                          |
| High error burst >5% prediction failures in 15 min       |
| Low-confidence surge>40% low/very-low predictions in day |
| Export instability >3% XML export failures in day        |
| Drift anomaly >20% shift in key distribution metrics     |

## 42. Security and Access Model

### 42.1 Data Sensitivity

```
Construction and article history are operationally sensitive engineering assets.
```

```
Recommended controls:
```

```
access logging
environment-segregated deployment
restricted write access for source data files
```

### 42.2 API Security Recommendations

```
1. Introduce authentication for non-public deployments.
2. Add rate limiting for prediction and export endpoints.
3. Validate payload size and numeric bounds.
4. Add request ID correlation for traceability.
```

### 42.3 Download Security Recommendations

```
Validate XML generation payload shape.
Prevent header injection in file naming.
Keep fixed filename unless role-authorized customization is added.
```

## 43. Deployment and Runtime Specification

### 43.1 Runtime Requirements

| Details                         |
| ------------------------------- |
| Component Requirement           |
| Python 3.11+                    |
| Backend Fast API + Uvicorn      |
| Frontend Next.js static export  |
| Port 7860 for container runtime |

### 43.2 Container Behavior

```
Container startup sequence:
```

```
1. Install dependencies.
2. Start Uvicorn app server.
3. Load datasets on first access.
4. Serve frontend static assets when available.
```

### 43.3 Production Readiness Checklist

| Details                               |
| ------------------------------------- |
| Item Required                         |
| Health endpoint stable Yes            |
| Data files available in container Yes |
| Frontend static files present Yes     |
| XML export endpoint verified Yes      |
| Validation endpoint tested Yes        |

### 43.4 Rollback Strategy

```
If release introduces prediction regression:
```

```
1. Roll back to previous container tag.
2. Restore prior shrinkage table version.
3. Re-run sanity validation set.
```

## 44. Program Governance and Operating Cadence

### 44.1 Weekly Cadence

```
Review low-confidence cases.
Review major comparative deltas.
Review API error and latency trends.
```

### 44.2 Monthly Cadence

```
Recalibrate weave shrinkage lookup with latest completed records.
Compare validation MAE month-over-month.
Approve documentation and logic changes through review board.
```

### 44.3 Quarterly Cadence

```
Evaluate roadmap readiness for CV pilot.
Audit formula assumptions against production outcomes.
Reassess confidence thresholds.
```

### 44.4 Governance Roles

| Details                                              |
| ---------------------------------------------------- |
| Role Responsibility                                  |
| Engineering Lead Logic changes and release integrity |
| PDC Domain Lead Formula and practicality sign-off    |
| QA Lead Regression and contract testing              |
| Product Owner Prioritization and roadmap tracking    |

## 45. Extended Business Impact Framework

### 45.1 Impact Dimensions

| Details                                                     |
| ----------------------------------------------------------- |
| Dimension Dimension Why It MattersWhy It Matters            |
| Speed Faster construction turnaround                        |
| Consistency Less engineer-to-engineer variance              |
| Explainability Better confidence in approvals               |
| Reuse Better historical learning utilization                |
| Error Containment Reduced propagation of incorrect patterns |

### 45.2 Impact Measurement Metrics

| Details                                                              |
| -------------------------------------------------------------------- |
| Metric Measurement Method                                            |
| Time-to-recommendation Timestamp delta from input to output          |
| Approval lead time Time from recommendation to engineer sign-off     |
| Rework incidence Count of revised constructions post-issue           |
| Divergence incidence Count of high delta historical-vs-formula cases |
| Export adoption Ratio of predictions exported as XML                 |

### 45.3 Decision Quality Indicators

```
Recommended tracking indicators:
```

```
percentage of high-confidence approvals
percentage of low-confidence overrides
formula-vs-historical convergence trend
post-approval correction frequency
```

### 45.4 Continuous Improvement Loop

```
Prediction Generated
↓
Engineer Decision Captured
↓
Production Outcome Recorded
↓
Comparison with Prediction
↓
Model/Table Calibration
↓
Next Prediction Improvement
```

## 46. Final Statement

```
This TRD formalizes the PDC platform as a comprehensive engineering intelligence system rather than a single-point
calculator. It defines:
```

```
current implementation logic,
formula and statistical decision layers,
comparative governance expectations,
operational export behavior,
and the phased AI evolution roadmap.
```

**Deployment:** Hugging Face Space `ascentialabs/PDC` (Docker, port 7860). Push to `main` triggers rebuild.

```
End of Technical Requirements Document
```