ForensIQ — Forensic Intelligence for Financial Filings

ForensIQ is an autonomous, multi-agent financial intelligence system engineered to scan, cross-examine, and discover accounting anomalies, consistency violations, and indicators of fraud within corporate financial disclosures.

By replacing complex browser automation with optimized REST/HTTP requests, parsing document structures locally, indexing text vectors inside PostgreSQL with pgvector, and using a cyclic LangGraph multi-agent orchestration engine, ForensIQ performs deep qualitative audits in seconds.

---

Key Features

• Autonomous Multi-Agent Interrogation: Uses LangGraph state machines to control agent cycles, allowing agents to collect, parse, audit, and synthesize findings dynamically.
• Playwright-Free Crawling: A lightweight, robust scraping engine that queries SEC EDGAR, BSE India, and NSE India APIs without the overhead of browser automation.
• Targeted RAG via pgvector: Chunks annual disclosures locally, generates embeddings using all-MiniLM-L6-v2, and stores them directly in PostgreSQL for fast semantic retrieval.
• Deterministic Anomaly Diagnostics: Runs calculations to detect revenue reversals, gross margin cliffs, and asset-revenue growth divergences.
• Statistical Auditing (Benford's Law): Computes a chi-squared goodness-of-fit test on the distribution of first digits across all extracted financial parameters.
• Live Operations Console: Built in React with Tailwind-inspired custom CSS and Recharts, streaming agent progress and analytics via WebSockets.

---

System Architecture

                       +----------------------------------+
                       |       React Frontend Dashboard   |
                       +----------------+-----------------+
                                        |
                          REST (HTTP)   |   WebSockets (WS)
                                        v
                       +----------------+-----------------+
                       |         FastAPI Server           |
                       +----------------+-----------------+
                                        |
                       +----------------v-----------------+
                       |      LangGraph Agent Engine      |
                       +----------------+-----------------+
                                        |
                 +----------------------+----------------------+
                 |                      |                      |
                 v                      v                      v
        +--------+--------+    +--------+--------+    +--------+--------+
        |  Crawler Agent  |    | Extractor Agent |    |  Pattern Agent  |
        |  (SEC/BSE/NSE)  |    |  (pgvector RAG) |    |  (Benford/LLM)  |
        +-----------------+    +-----------------+    +-----------------+

---

Folder Structure

.
├── api/                   # FastAPI Backend
│   ├── agents/            # LangGraph multi-agent nodes & state definitions
│   ├── api/               # Router endpoints (health, investigations, ws)
│   ├── core/              # Config, DB connections, WebSocket manager
│   ├── db/                # Models, schemas, vector operations, init.sql
│   ├── graph/             # Compiled LangGraph definition
│   ├── modules/           # Mathematical routines (Benford's Law)
│   ├── requirements.txt   # Python packages
│   └── main.py            # API App entry point
├── frontend/              # Vite + React Frontend
│   ├── src/               # React codebase (components, pages, styles)
│   ├── index.html         # Main page template
│   └── package.json       # Node modules & scripts
├── docker-compose.yml     # Multi-container orchestrator
└── README.md              # Documentation

---

Installation & Setup

Prerequisites

Ensure you have the following installed on your machine:

• Docker and Docker Compose
• Python 3.13+ (if running outside Docker)
• Node.js 18+ (if running frontend locally)

Step 1: Environment Variables

Copy the example environment file:

cp .env.example .env

Edit the .env file to configure your variables. One LLM provider key is required to run the pattern and narrative agents:

# Choose provider: "groq" | "anthropic" | "openai"
LLM_PROVIDER=groq
LLM_MODEL=llama-3.3-70b-versatile

# API Keys
GROQ_API_KEY=gsk_...
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...

# PostgreSQL Configurations
POSTGRES_USER=forensiq
POSTGRES_PASSWORD=forensiq_secret
POSTGRES_DB=forensiq
DATABASE_URL=postgresql+asyncpg://forensiq:forensiq_secret@postgres:5432/forensiq

---

Step 2: Running via Docker Compose (Recommended)

To build and run all services in a single command:

docker compose up --build

This starts:

1. PostgreSQL + pgvector: Database container listening on port 5432.
2. FastAPI Backend: API container listening on port 8000.
3. Vite React Frontend: UI container listening on port 3000.

Once started, navigate to http://localhost:3000 to access the dashboard.

---

Step 3: Running Locally (Development Mode)

If you prefer to run the database in Docker but run the code locally, follow these steps:

1. Start the Database

docker compose up postgres -d

2. Run the Backend API

Create a virtual environment and install packages:

cd api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run database migrations/table setup and start the server:

python3 main.py

The API docs will be available at http://localhost:8000/docs.

3. Run the React Frontend

Open a new terminal tab:

cd frontend
npm install
npm run dev

The application will start at http://localhost:3000.

---

API Specifications

Core Endpoints

• POST /api/v1/investigations: Start a new investigation task.

  {
    "company": "AAPL",
    "goal": "Audit revenue and asset consistency check",
    "years": [2021, 2022, 2023]
  }

• GET /api/v1/investigations: Retrieve list of all investigations.
• GET /api/v1/investigations/{id}: Fetch detailed findings, flags, agent traces, and report.
• DELETE /api/v1/investigations/{id}: Delete an investigation run and its associated filings.
• GET /ws/{run_id}: WebSocket connection to stream live agent steps.

---

Testing

To run the unit tests:

cd api
.venv/bin/pytest tests

---

Contributing

1. Fork the Project repository.
2. Create your Feature Branch (git checkout -b feature/NewFeature).
3. Commit your Changes (git commit -m 'Add NewFeature').
4. Push to the Branch (git push origin feature/NewFeature).
5. Open a Pull Request.

---

License

Distributed under the MIT License. See LICENSE for more information.