README.md

---
title: PDC Intelligence
emoji: 🧵
colorFrom: purple
colorTo: blue
sdk: docker
sdk_version: "3.11"
app_port: 7860
pinned: false
---

# PDC Intelligence Prototype (MVP)

This prototype is built under `PDC/` and aligned to the PDC meeting notes and process documents.

## Scope Covered

- Phase-1 focus: greige construction recommendation from finish-side requirements.
- Dashboard for dataset health, coverage, and core relativity metrics.
- Article search with filters and article-level detail.
- Construction calculator with optimistic/expected/pessimistic scenarios.
- Relativity analytics by weave/blend and numeric correlation matrix.
- Feasibility process flow mapping from meeting/process docs.
- Built-in validation report endpoint for ongoing prediction quality checks.

## Folder Layout

- `backend/`: FastAPI APIs and statistical engine.
- `frontend/`: Next.js dashboard and calculator UI.
- `backend/app/data/`: copied data files for runtime.

## Backend Run

```bash
cd backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn app.main:app --reload --port 8000
```

## Frontend Run

```bash
cd frontend
npm install
npm run dev
```

Frontend rewrites `/api/*` to backend `http://localhost:8000/api/*`.

## One-command Run

From `PDC/`:

```bash
./run_app.sh
```

This script will:

- create backend venv if missing
- install backend dependencies
- run backend tests before startup
- install frontend dependencies
- start backend and frontend together

## Verification Performed

- Unit tests:
  - formula correctness checks
  - prediction response contract checks
  - holdout MAE threshold checks
  - validation report generation checks

Run tests:

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

Current run: `3 passed`

Validation API:

```bash
GET /api/validation/report?sample_size=250&seed=42
```

Returns MAE, error percentiles, and confidence distribution.

Data source audit API:

```bash
GET /api/data-source/audit
```

Returns source file usage, raw vs used row counts, dataset distribution, and column-level null coverage.

## Predictive Validation Snapshot

On a 300-row holdout sample:

- MAE (Greige EPI): `13.92`
- MAE (Greige PPI): `8.132`
- P90 absolute error (Greige EPI): `33.0`
- P90 absolute error (Greige PPI): `20.0`

These are baseline MVP metrics and can be improved by adding tighter cluster filters (count band, loom, weave aliases) and weighted neighbors.