# 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.