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)

┌────────────────────────────────────────────────────────────────────┐

│ 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)

┌────────────────────────────────────────────┐
│ 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:

{ "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 < 4 and within 4 ends of formula target.
4. Evaluate Stockport reed candidates from archive matches plus formula-derived reeds when archive options are >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 — 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)

{
  "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)

{
  "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

10.4 Unit Test Suite (v2.2)

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

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

greige_epi_approx = reed_count * ends_per_dent

21.1.3 Cover Factor

cover_factor = epi * sqrt(count)

21.1.4 Width Approximation

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)

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)

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

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

┌──────────────────────────┐
│ 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)

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)

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
UI-R-002
UI-R-003
UI-R-004
UI-R-005
UI-R-006

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