🚗 Car Damage Assessment AI — Internal POC

Internal Proof of Concept
Designed as an internal demo for insurance, fleet management, and automotive damage decision workflows, where explainability, auditability, and human control are critical.
High-trust vehicle damage assessment system combining Computer Vision, deterministic policy-driven decisioning, human-in-the-loop governance, and optional LLM guidance.

💼 Why this matters commercially

This system demonstrates how AI-assisted decisioning can:

• Reduce operator workload by auto-approving low-risk, well-defined cases
• Standardize decisions across teams, regions, and partners using explicit policies
• Accelerate triage and escalation, improving customer response times without sacrificing trust or control

🧠 Problem

Vehicle damage intake and triage remains slow, inconsistent, and expensive:

• Manual inspections do not scale
• Decisions vary across operators and regions
• Escalation rules are implicit and poorly documented
• Auditability and explainability are often missing
• Humans are either overloaded or bypassed entirely

This POC shows how AI-assisted decisioning can standardize assessment without removing human control.

🎯 What this POC demonstrates

• ✅ Computer Vision damage detection (demo / model-backed, YOLO-compatible interface)
• ✅ Deterministic, policy-driven decisioning (AUTO_APPROVE, HUMAN_REVIEW, ESCALATE)
• ✅ Explainability by design (Decision Trace + SOP evidence)
• ✅ Human-in-the-loop governance (override + audit log)
• ✅ Optional LLM guidance (non-critical, fully disableable)
• ✅ Production-style Streamlit UX with strong demo value ("wow" moments)
• ✅ REST API for integration into existing claims pipelines
• ✅ Automated test suite (22 tests) with CI/CD pipeline

🏗 High-Level Architecture

[ Vehicle Image ]
        |
        v
[ CV Detection ]
 (demo / model-backed)
        |
        v
[ Normalized Damage Signal ]
        |
        v
[ Decision Agent ]
   ├─ Rules & thresholds
   ├─ Policy (YAML)
   └─ SOP evidence (Markdown)
        |
        v
[ Decision Output ]
   ├─ AUTO_APPROVE
   ├─ HUMAN_REVIEW
   └─ ESCALATE
        |
        v
[ Human Override ]
 (optional, always auditable)
        |
        v
[ REST API / Streamlit UI ]
 (integration or demo)

🧭 Decision philosophy

• Decisions are deterministic by default
• Policies and thresholds are explicit and versioned
• Every decision produces a traceable explanation
• Humans can override any outcome
• Overrides are treated as first-class governance events

🤖 Why the LLM is optional

• Core decisions do not rely on generative AI
• LLM is used only for:
  • operator guidance
  • repair explanations
  • UX storytelling
• Disabling the LLM does not affect correctness
• System remains safe for regulated environments

---

🔌 REST API

The system includes a FastAPI-based REST API for programmatic access — enabling integration into existing claims pipelines, fleet management systems, or third-party platforms.

Quick start (API)

pip install -r requirements-api.txt
python api.py
# API running at http://localhost:8000
# Interactive docs: http://localhost:8000/docs

Endpoints

Method	Endpoint	Description
POST	/assess	Upload image → get damage assessment with decision trace
GET	/health	System health check and module availability
GET	/policy	Current policy configuration and decision rules
GET	/docs	Interactive Swagger UI documentation

Example: assess vehicle damage via curl

curl -X POST http://localhost:8000/assess \
  -F "image=@photo_of_car.jpg" \
  | python -m json.tool

Example response

{
  "assessment_id": "a1b2c3d4e5f6",
  "timestamp": "2026-05-11T20:30:00+00:00",
  "processing_time_ms": 47,
  "damages_detected": [
    {
      "damage_type": "scratch",
      "confidence": 0.87,
      "severity": "minor",
      "location": "rear_bumper"
    },
    {
      "damage_type": "dent",
      "confidence": 0.73,
      "severity": "moderate",
      "location": "front_door_left"
    }
  ],
  "total_damages": 2,
  "decision": "HUMAN_REVIEW",
  "decision_confidence": 0.75,
  "decision_trace": [
    {
      "rule_applied": "moderate_damage_review",
      "threshold": "severity == moderate",
      "evidence": "Policy: Moderate damage detected → human review recommended"
    }
  ],
  "model_version": "demo-v0.1",
  "policy_version": "v1.0-demo",
  "cv_backend": "demo",
  "human_review_required": true
}

Example: health check

curl http://localhost:8000/health | python -m json.tool

{
  "status": "healthy",
  "version": "0.1.0",
  "cv_available": false,
  "agent_available": false,
  "uptime_seconds": 12.3
}

---

🖥 Demo flow (Streamlit UI)

1. Upload vehicle image
2. Detect visible damages (demo or CV-backed)
3. Normalize detections into a damage signal
4. Decision Agent evaluates policies and thresholds
5. Decision Trace explains why the outcome was chosen
6. Operator may override the decision (logged)
7. Repair Strategy Simulator & Before/After Preview provide UX "wow"

🖼 UI walkthrough (screenshots)

Screenshots are in: docs/screenshots/
Recommended order:

1. 01_app_overview_dashboard.png — main dashboard
2. 02_image_upload_input.png — image upload
3. 03_damage_detection_results.png — CV detections
4. 04_agent_decision_human_review.png — decision trace & human review
5. 05_before_after_damage_visualization.png — before/after preview
6. 06_assessment_summary_and_analytics.png — analytics & charts
7. 07_assessment_report_and_export.png — report & export

🛠 Technology stack

• UI: Streamlit
• API: FastAPI + Uvicorn
• Computer Vision: OpenCV (YOLO-compatible interface)
• Decisioning: rule-based agent + policy YAML
• Policies / SOPs: Markdown + YAML
• Retrieval (optional): lightweight KB lookup
• LLM (optional): guidance only (no decision authority)
• Visualization: Plotly
• Testing: pytest (22 tests)
• CI/CD: GitHub Actions
• Runtime: Python 3.11+
• Deployment: Docker & Docker Compose
• GPU dependencies are not required

📦 Dependency strategy

Separated dependency layers:

• requirements.txt — local / full environment
• requirements-api.txt — REST API layer (FastAPI, Uvicorn)
• requirements-dev.txt — dev utilities
• requirements-llm.txt — optional LLM integration
• requirements.docker.txt — minimal runtime deps (Docker)

This keeps Docker images small and predictable.

🧪 Testing

# Run all tests
pytest tests/ -v

# Run specific test group
pytest tests/test_api.py::TestHealth -v
pytest tests/test_api.py::TestAssessment -v
pytest tests/test_api.py::TestValidation -v

Tests cover:

• API health and status reporting
• Image upload and assessment flow
• Response structure and decision trace presence
• Input validation (file type, size limits)
• Policy endpoint and OpenAPI docs

🚀 Quick start (local, no Docker)

git clone https://github.com/artemxdata/Car-Damage-Assessment-AI.git
cd Car-Damage-Assessment-AI

python -m venv .venv
source .venv/bin/activate        # Linux/Mac
# .venv\Scripts\Activate.ps1     # Windows PowerShell

pip install -r requirements.txt
pip install -r requirements-api.txt

# Option 1: Streamlit UI
streamlit run app.py
# Open: http://localhost:8501

# Option 2: REST API
python api.py
# Open: http://localhost:8000/docs

🐳 Docker (recommended)

Build & run

docker build -t car-damage-ai:cpu .  
docker run --rm -p 8501:8501 car-damage-ai:cpu

Docker Compose

docker-compose up --build

🧠 Runtime vs Source Architecture (Important Note)

The Docker setup intentionally runs a minimal runtime image.

Core system intelligence — including:

• agentic decision logic
• policy evaluation (YAML)
• SOP evidence (Markdown)
• decision trace and human override mechanisms

—is part of the source code and is fully executed inside the container at runtime.

Development tooling, experimentation utilities, and optional LLM integrations are intentionally kept outside the runtime image to keep deployments:

• lightweight
• deterministic
• production-aligned

This separation mirrors real-world enterprise deployment practices, where runtime environments remain minimal while decision logic stays explicit, traceable, and auditable.

---

Services:

• app — Streamlit UI + decision engine

Ports:

• 8501 — Web UI (Streamlit)
• 8000 — REST API (FastAPI)

---

⚙ Configuration

Environment variables (optional):
LLM_BASE_URL=
LLM_API_KEY=
LLM_MODEL=
CONFIDENCE_THRESHOLD=0.5

LLM can be fully disabled without breaking the system.

---

📁 Project structure

Car-Damage-Assessment-AI/  
├── app.py                    # Streamlit UI
├── api.py                    # FastAPI REST endpoint
├── car_damage_detector.py    # CV detection module
├── utils.py                  # Shared utilities
├── agentic/                  # Decision agent logic
├── policies/                 # YAML policy definitions
├── knowledge/                # SOP evidence (Markdown)
├── models/                   # CV model weights
├── data/                     # Sample images
├── docs/                     # Documentation & screenshots
├── outputs/                  # Detection output images
├── tests/                    # Automated test suite
│   └── test_api.py           # API endpoint tests (22 tests)
├── .github/
│   └── workflows/
│       └── ci.yml            # GitHub Actions CI pipeline
├── Dockerfile
├── docker-compose.yml
├── requirements.txt          # Core dependencies
├── requirements-api.txt      # API layer dependencies
├── requirements-dev.txt      # Dev utilities
├── requirements-llm.txt      # Optional LLM deps
├── requirements.docker.txt   # Minimal Docker deps
└── README.md

🧪 What this is (and is not)

This is:

• a serious internal POC
• a decision-centric architecture demo
• a strong product & UX prototype
• an integration-ready system (REST API)

This is NOT:

• a production insurance system
• a fully trained CV model
• a replacement for human judgment

---

📈 Future directions

• Model-backed CV inference (YOLOv8 on real damage datasets)
• Multi-image / video ingestion
• Policy versioning & analytics
• Audit log persistence
• PDF / claims system export
• Landing page & pilot program

---

📄 License

MIT License

---

👤 Author

Artem (@artemxdata) — AI / Agentic Systems Engineering
Focused on high-trust, explainable AI systems