# Vehicle Authenticity Due Diligence Toolkit

A compact Python toolkit for structuring vehicle authenticity evidence, scoring due diligence risk, and generating concise review reports.

This repository is a public-safe demonstration project. It uses fictional demo data and is designed to show how technical vehicle analysis, evidence governance, and automated reporting can be translated into reproducible software workflows.

## What It Does

- Loads structured vehicle and evidence data from JSON
- Scores authenticity risk across identity, provenance, technical consistency, documentation, and inspection findings
- Flags missing or contradictory evidence
- Generates a Markdown due diligence report
- Provides a small CLI for repeatable analysis

## Why This Exists

Historic vehicle due diligence is often handled through expert judgment, scattered documents, and unstructured notes. This project demonstrates how that work can be translated into a transparent software workflow without replacing the expert.

The goal is not to produce a final authenticity opinion automatically. The goal is to make evidence review more structured, reproducible, and easier to communicate.

## Example Use Cases

- Collector due diligence pre-screening
- Historic vehicle documentation review
- Evidence matrix preparation
- Internal authenticity review workflows
- AI-assisted report pipelines with human expert review

## Quick Start

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
vehicle-authenticity examples/demo_case.json --output examples/demo_report.md
```

A generated reference report is included at `examples/sample_report.md`.

## Project Structure

```text
src/vehicle_authenticity_toolkit/
  __main__.py      CLI entry point
  models.py        Typed case and evidence models
  scoring.py       Due diligence risk scoring
  reporting.py     Markdown report generation
examples/
  demo_case.json   Fictional public-safe example case
tests/
  test_scoring.py  Basic scoring regression tests
```

## Design Principles

- Expert-led, software-supported
- Transparent scoring rather than opaque claims
- Evidence quality matters as much as evidence volume
- Demo data only; no client or confidential material
- Outputs are decision-support notes, not final legal or valuation opinions

## Scoring Model

The current model applies weighted category scoring:

- Identity: 30%
- Technical consistency: 25%
- Provenance: 20%
- Documentation: 15%
- Inspection completeness: 10%

Each evidence item contributes risk based on status and confidence. Contradictory, missing, and unknown evidence create explicit findings in the generated report.

## Roadmap

- PDF report export
- Evidence attachment index
- Contradiction detection rules
- CSV batch analysis
- Optional LLM-assisted summary drafting
- Streamlit dashboard for non-technical users

## Development

```bash
source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest -q
```

## License

MIT