ClaimCheck

ClaimCheck is an evidence-grounded insurance policy reasoning engine.

Prerequisites

• Python 3.11+
• Docker & Docker Compose

Running the Database

Start PostgreSQL with pgvector:

docker compose up -d db

Backend Setup

1. Navigate to the backend directory:

   cd backend

2. Create and activate a virtual environment:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # Linux/macOS:
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment variables:

   cp .env.example .env

   Generate a secure random secret key for JWT_SECRET_KEY in production/staging:

   python -c "import secrets; print(secrets.token_urlsafe(48))"

5. Run the FastAPI development server:

   uvicorn app.main:app --reload

Authentication Endpoints

1. Register User

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "StrongPassword123!"}'

2. Login User

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "StrongPassword123!"}'

3. Get Current User (/me)

curl -X GET http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Database Migrations

Run Alembic migration commands from the backend/ directory:

• Apply all pending migrations:

  alembic upgrade head

• Roll back the latest migration:

  alembic downgrade -1

• Generate a new migration revision based on ORM model changes:

  alembic revision --autogenerate -m "message"

Running Tests

pytest -q

Policy Upload

Uploaded PDFs are stored at data/uploads/<user_id>/<policy_id>/<version_id>.pdf (relative to the backend/ directory). Only PDF files are accepted; the server validates both the declared Content-Type and the file magic bytes.

1. Upload a Policy (multipart/form-data)

curl -i -X POST http://localhost:8000/api/policies \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -F "name=My Health Plan" \
  -F "provider=Acme Insurance" \
  -F "policy_type=Health" \
  -F "file=@/path/to/policy.pdf"

2. List Policies

curl http://localhost:8000/api/policies \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

3. Get a Single Policy

curl http://localhost:8000/api/policies/<POLICY_ID> \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

4. Delete a Policy

curl -X DELETE http://localhost:8000/api/policies/<POLICY_ID> \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"