cmm-report-analyzer/README.md

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

git clone https://git.deathstar-home.one/chrisryn/cmm-report-analyzer.git
cd cmm-report-analyzer

2. Create a virtual environment

python3 -m venv .venv

Activate it:

# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (CMD)
.venv\Scripts\activate.bat

3. Install dependencies

pip install -e .

To also install dev/test dependencies:

pip install -e ".[dev]"

4. Configure environment variables

Copy the example file:

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

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Then open your browser to http://localhost:8000.

6. Run tests

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.