From 3701809bbf034d5ada2808f6cb96e2a0912bb1d4 Mon Sep 17 00:00:00 2001
From: chrisryn <chrisryn@deathstar-home.one>
Date: Thu, 19 Feb 2026 10:52:25 -0600
Subject: [PATCH] Add setup documentation

README with prerequisites, install steps, usage guide,
supported formats, project structure, and API reference.
---
 README.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a6dfc53
--- /dev/null
+++ b/README.md
@@ -0,0 +1,153 @@
+# CMM Report Analyzer
+
+A FastAPI web application that parses CMM (Coordinate Measuring Machine) inspection reports, computes SPC metrics, generates interactive charts, and provides AI-powered quality summaries.
+
+## Prerequisites
+
+- Python 3.11 or higher
+- pip (comes with Python)
+- Git
+
+## Setup
+
+### 1. Clone the repository
+
+```bash
+git clone https://git.deathstar-home.one/chrisryn/cmm-report-analyzer.git
+cd cmm-report-analyzer
+```
+
+### 2. Create a virtual environment
+
+```bash
+python3 -m venv .venv
+```
+
+Activate it:
+
+```bash
+# Linux / macOS
+source .venv/bin/activate
+
+# Windows (PowerShell)
+.venv\Scripts\Activate.ps1
+
+# Windows (CMD)
+.venv\Scripts\activate.bat
+```
+
+### 3. Install dependencies
+
+```bash
+pip install -e .
+```
+
+To also install dev/test dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+### 4. Configure environment variables
+
+Copy the example file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your values:
+
+| Variable | Description | Required |
+|---|---|---|
+| `AZURE_OPENAI_ENDPOINT` | Your Azure OpenAI resource URL (e.g. `https://your-resource.openai.azure.com`) | No |
+| `AZURE_OPENAI_API_KEY` | Your Azure OpenAI API key | No |
+| `AZURE_OPENAI_DEPLOYMENT` | Deployment name (default: `gpt-4o`) | No |
+| `AZURE_OPENAI_API_VERSION` | API version (default: `2024-10-21`) | No |
+
+> **Note:** The Azure OpenAI settings are optional. Without them, the app will still work fully -- it will generate a rule-based fallback summary instead of an AI-powered one.
+
+### 5. Run the app
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Then open your browser to **http://localhost:8000**.
+
+### 6. Run tests
+
+```bash
+pytest tests/ -v
+```
+
+## Usage
+
+1. Open the web UI at `http://localhost:8000`
+2. Drag and drop (or browse for) one or more CMM report files
+3. Supported file types: `.pdf`, `.xlsx`, `.xls`, `.csv`
+4. Click **Analyze Files**
+5. View results including:
+   - **AI/rule-based quality summary** -- pass/fail assessment, features of concern, corrective actions
+   - **SPC metrics table** -- Cp, Cpk, Pp, Ppk, control limits, out-of-spec counts per feature
+   - **Interactive charts** -- distribution histograms, control charts, capability bar chart (powered by Plotly)
+   - **Full measurement details** -- expandable table with per-measurement tolerance status
+
+## Supported Report Formats
+
+The parsers use fuzzy column-name matching, so your files don't need exact header names. The app looks for columns matching these patterns:
+
+| Field | Recognized headers (partial match) |
+|---|---|
+| Feature name | feat, char, dimen, label, id, name, item |
+| Nominal | nom, target, blueprint, print |
+| Actual | actual, meas, value, result, reading |
+| Tolerance + | tol+, upper tol, usl, pos tol |
+| Tolerance - | tol-, lower tol, lsl, neg tol |
+| Deviation | dev, diff, error, delta |
+
+For PDF files, the parser also extracts metadata such as part number, serial number, inspection date, program, and operator from the report text.
+
+## Project Structure
+
+```
+app/
+  main.py              FastAPI entrypoint
+  config.py            Settings (.env loading)
+  routers/
+    upload.py           POST /api/upload
+    results.py          GET /api/results/{batch_id}
+  parsers/
+    models.py           MeasurementRecord, ParsedReport
+    base.py             Abstract parser, fuzzy column matching
+    excel_parser.py     Excel/CSV parser (pandas + openpyxl)
+    pdf_parser.py       PDF parser (pdfplumber)
+  analysis/
+    spc.py              SPC calculations (Cp/Cpk/Pp/Ppk, Shapiro-Wilk)
+    charts.py           Plotly chart generation
+  ai/
+    summarizer.py       Azure OpenAI summary with fallback
+  services/
+    batch.py            Orchestration pipeline (parse -> SPC -> charts -> summary)
+  static/
+    index.html          Web UI
+    css/style.css       Styles
+    js/app.js           Frontend logic
+tests/
+  test_api.py           API integration tests
+  test_parsers.py       Parser unit tests
+  test_spc.py           SPC calculation tests
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/api/upload` | Upload one or more CMM report files. Returns `{ batch_id, file_count }`. |
+| `GET` | `/api/results/{batch_id}` | Retrieve analysis results for a batch. Returns SPC metrics, charts, and summary. |
+
+## Notes
+
+- Results are stored **in memory only** and are lost when the server restarts.
+- Maximum upload size is 50 MB per file (configurable via `MAX_UPLOAD_MB` env var).
+- The app accepts multiple files in a single upload and processes them concurrently.