Fraud Analyst Agent

A multi-agent fraud-detection service built with CrewAI. It analyses time-series sensor measurements from waste-disposal sessions to flag anomalous usage patterns that indicate tampering, and exposes the result through a FastAPI endpoint.

How It Works

The crew runs two agents in sequence:

1. SQL Executor — queries the PostgreSQL database for the ordered measurement series of a given waste session.
2. Fraud Detector — analyses the series for fraud indicators (flat or highly uniform readings, lack of expected growth over the session, negligible change between first and last values) and returns a structured verdict.

A DeepSeek chat model drives both agents, and the final task emits a validated JSON result.

Tech Stack

Area	Tools
Agent framework	CrewAI
LLM	DeepSeek (deepseek-chat)
API	FastAPI + Uvicorn
Database	PostgreSQL + pgvector
Language	Python 3.10–3.12

Setup

This project uses uv for dependency management.

# 1. Install uv
pip install uv

# 2. Install dependencies
uv sync

# 3. Configure environment
cp .env.example .env   # then fill in the values

Required environment variables (see .env.example):

Variable	Purpose
DEEPSEEK_API_KEY	DeepSeek LLM access
DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, DB_NAME	PostgreSQL connection

Usage

Run the crew directly:

crewai run

Or serve the FastAPI endpoint:

uvicorn fraud_analyst.server:app --reload

Send a detection request to POST http://127.0.0.1:8000/detect-fraud/:

Request

{
  "user_id": "1234567890",
  "waste_session_id": "1234567890"
}

Response

{
  "user_id": "1234567890",
  "waste_session_id": "1234567890",
  "possible_fraud": "yes",
  "reason": [
    "1. Measurements stay within a narrow range (30.74–34.44) across 46 transactions, showing no significant growth over time.",
    "2. The first (32.78) and final (31.85) values are nearly identical, indicating no explainable change."
  ]
}

Project Structure

src/fraud_analyst/
├── main.py              # Crew entry points (run/train/replay/test)
├── server.py            # FastAPI service exposing /detect-fraud/
├── crew.py              # Crew, agent and task definitions
├── tools/
│   └── db_tools.py      # PostgreSQL query tool
└── config/
    ├── agents.yaml      # Agent roles, goals and backstories
    └── tasks.yaml       # Task descriptions and expected outputs

Customise agent and task behaviour via the YAML files in config/, and adjust crew wiring in crew.py.

License

Released under the MIT License.