Add setup documentation
README with prerequisites, install steps, usage guide, supported formats, project structure, and API reference.
This commit is contained in:
chrisryn
153
README.md
Normal file
153
README.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user