# Forensic Evidence Graph

A technically oriented Python engine for modeling forensic due diligence cases as evidence graphs, evaluating consistency rules, and generating risk intelligence outputs.

This public-safe demonstration project uses fictional data. It is designed for authenticity, provenance, inspection, and evidence-governance workflows where expert judgment must remain traceable.

## What It Does

- Models claims, evidence, sources, findings, and contradictions as a graph
- Calculates graph metrics such as degree centrality, connected components, and unsupported claims
- Evaluates forensic consistency rules
- Scores risk across identity, provenance, technical, documentation, and inspection domains
- Detects timeline gaps and high-impact contradictions
- Exports Markdown, JSON, and Graphviz DOT outputs
- Runs offline with the Python standard library

## Why This Exists

High-value due diligence often depends on fragmented evidence: documents, inspection findings, provenance claims, technical observations, and expert notes. A graph model makes relationships visible and allows risks to be evaluated in a transparent, auditable way.

This project demonstrates how expert-led vehicle forensic analysis can be translated into a reproducible evidence-governance engine.

## Quick Start

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
evidence-graph examples/demo_case.json --report examples/report.md --json examples/analysis.json --dot examples/graph.dot
```

Reference outputs are included at:

- `examples/sample_report.md`
- `examples/sample_analysis.json`
- `examples/sample_graph.dot`

## Project Structure

```text
src/forensic_evidence_graph/
  __main__.py       CLI entry point
  models.py         Typed graph data models
  graph.py          Graph construction and metrics
  rules.py          Forensic rule engine
  scoring.py        Risk aggregation
  exporters.py      Markdown, JSON, and DOT export
examples/
  demo_case.json
tests/
  test_graph.py
  test_rules.py
  test_scoring.py
```

## Technical Concepts

- Directed evidence graph
- Weighted source reliability
- Claim support and contradiction mapping
- Rule-based risk detection
- Domain-level risk aggregation
- Timeline gap detection
- Deterministic, inspectable outputs

## Development

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

## Roadmap

- Evidence attachment index
- Temporal graph queries
- Confidence propagation models
- Interactive graph visualization
- Optional LLM-assisted narrative drafting
- PDF report export

## License

MIT