AuditMind

An experimental contract-review application that extracts clauses from PDFs, retrieves a user's policy rules, and drafts suggested revisions with language models.

Status: local prototype. The repository demonstrates a three-stage AI workflow, a FastAPI backend, and a browser dashboard. It has no published accuracy evaluation or production deployment validation. Findings require human review.

What is implemented

• PDF text extraction with PyMuPDF and clause extraction with Gemini.
• A per-user policy index built with LlamaIndex and Gemini embeddings, queried through Groq.
• Suggested clause revisions generated with Gemini, stored alongside findings in SQLite.
• Signup/login, document upload, progress updates over WebSockets, and a report view.
• Experimental Stripe subscription checkout, customer portal, and webhook handling; custom-policy uploads require a pro account.

Architecture

flowchart LR
    UI[Browser dashboard] --> API[FastAPI routes]
    API --> DB[(SQLite)]
    API --> PDF[Uploaded PDF]
    PDF --> Extract[PyMuPDF + Gemini clause extraction]
    Policy[Uploaded user policy] --> Index[LlamaIndex + Gemini embeddings]
    Extract --> Audit[Groq retrieval-based audit]
    Index --> Audit
    Audit --> Draft[Gemini suggested revisions]
    Draft --> DB
    DB --> Report[Report endpoint]
    Report --> UI
    Extract -. Progress .-> WS[WebSocket updates]
    Audit -. Progress .-> WS
    Draft -. Progress .-> WS
    WS -.-> UI

Loading

The application uses compliance.db and storage/ relative to the working directory. Run it from the repository root. User policies live in storage/rules/user_<id>/policy.md; the sample rules/policy.txt is not loaded automatically.

Local setup

Use Python 3.10 or 3.11 in a virtual environment. Gemini and Groq credentials are required for the AI workflow. Their configured models must also be available to your account; package installation alone does not establish model availability.

git clone https://github.com/RAMZI0TO99/AuditMind.git
cd AuditMind
python -m venv .venv

Activate the environment with .venv\Scripts\Activate.ps1 in PowerShell, or source .venv/bin/activate on macOS/Linux, then install dependencies:

python -m pip install -r requirements.txt

Copy .env.example to .env (Copy-Item .env.example .env in PowerShell or cp .env.example .env on macOS/Linux) and replace its placeholders:

Variable	Purpose
JWT_SECRET_KEY	A long, random secret for signing and validating login tokens. Set it explicitly.
GEMINI_API_KEY	Clause extraction, embeddings, and suggested revisions.
GROQ_API_KEY	Retrieval-based clause auditing.
STRIPE_SECRET_KEY	Test-mode secret key when exercising payment routes.
STRIPE_WEBHOOK_SECRET	Test webhook signing secret for /api/webhook.
FRONTEND_URL	Local redirect origin; use http://127.0.0.1:8000.

python -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload

Open http://127.0.0.1:8000 for the dashboard or http://127.0.0.1:8000/docs for the API. The interface also uses external CDN assets, so full styling requires internet access.

Try the workflow

1. Create a local account and sign in.
2. For a local demo, use the authenticated development endpoint GET /api/dev/force-pro with your Bearer token to enable policy uploads. This route changes the account tier and must be removed or restricted before any public deployment.
3. Upload a small .md or .txt rulebook through the Knowledge Base panel. Each upload replaces that user's previous policy.
4. Upload a text-based PDF, follow the extraction/audit/drafting progress, and inspect the resulting findings, cited rules, and suggested revisions.

Upload a policy before auditing. If there is no policy, or building its index fails, the current implementation returns an empty findings list and the interface can label the document compliant. An empty report is not evidence of compliance. Check the server output to confirm that the policy index loaded.

Optional payment testing

The Python Stripe SDK is declared in requirements.txt. The Stripe CLI is a separate, optional development tool: install it using the official Stripe CLI instructions, then follow Stripe's test-mode webhook-forwarding workflow for http://127.0.0.1:8000/api/webhook and set the resulting signing secret in .env. Use test credentials and test payment data only.

The CLI is not required to start the application. Keep downloaded CLI binaries outside the repository.

Known limitations

• The source uses legacy Gemini integrations that are no longer supported. Dependencies retain those import paths for compatibility; migration to Google GenAI remains future work.
• Model IDs are hard-coded in agents.py: models/gemini-3.1-flash-lite-preview, llama-3.3-70b-versatile, models/embedding-001 for the global embedding setting, and models/gemini-embedding-001 for user-policy indexing. These IDs have not been validated against live providers, and the two embedding settings differ.
• Clause extraction sends only the first 15,000 text characters to Gemini. There is no OCR stage, and scanned PDFs may contain no extractable text.
• Malformed model responses can lead to missed findings. Confidence scores and citations are model outputs, with defaults in the pipeline, rather than calibrated evaluation results.
• The development tier endpoint, upload validation, WebSocket authorization, generated-content rendering, and subscription lifecycle handling need further work before public deployment. Keep this prototype bound to localhost and use sample documents.
• Processing uses in-process background tasks and rebuilds the policy index for each document. Durable jobs, retries, concurrency/load testing, and an evaluation dataset are not implemented.

Dependency resolution and source checks do not validate end-to-end inference or billing. Live provider compatibility, payment flows, and model accuracy remain unverified.

License

See LICENSE.