FirAI — Kerala Police AI Investigation Assistant

AI-powered investigation assistant built for Kerala Police officers — providing real-time FIR analysis, case intelligence, legal guidance, and multilingual support using a 100% custom-built AI engine.

🏛️ Built for the Kerala AI Mission (K-AI) under Kerala Startup Mission (KSUM) — AI for smart governance & public good.

Overview
Screenshots
FirAI Engine — Custom AI
Architecture
Prerequisites
Step 1 — Install Docker
Step 2 — Clone the Repository
Step 3 — Configure Environment
Step 4 — Train the AI Model
Step 5 — Run the Project
Verify Everything Works
Features
Project Structure
Environment Variables
API Endpoints
Common Issues & Fixes
Tech Stack
Kerala AI Mission (K-AI) & Kerala Startup Mission
License

Overview

Kerala Police officers face fragmented processes when accessing FIRs, case updates, and legal procedures. FirAI solves this with an AI-powered investigation dashboard that:

Parses FIR narratives (Malayalam & English) and classifies crimes with relevant IPC/BNS sections
Finds similar past cases using multi-dimensional smart similarity (narrative embeddings + accused identity matching + crime type filtering)
Detects Modus Operandi (MO) patterns across FIRs to identify recurring crime methods
Provides AI legal guidance via a built-in Indian legal knowledge base, with optional Claude AI for conversational answers
Protects sensitive data via JWT-based officer authentication and a registration portal with admin approval
Centralises all FIR data with original PDF/image document storage and retrieval
Auto-names and deduplicates uploaded FIR files using extracted metadata (FIR number, year, police station)
Translates narratives between Malayalam and English via Bhashini API

Core Principle: Narrative-Centric

The FIR narrative (Section 12 — First Information Contents) is the backbone of the entire system. All AI analysis, similarity search, crime classification, and pattern detection flows from the narrative text.

📸 Screenshots

Login	Dashboard

FIR Analyzer	MO Patterns

Legal Assistant

FirAI Engine — Custom AI

FirAI uses a 100% custom-built AI system called FirAI Engine. Every model is designed, trained, and owned by this project. Classification, summarization, entity extraction, and legal mapping all run offline with no external API calls.

How It Works

The AI learns directly from Indian law texts (IPC, BNS, CrPC, BNSS, Kerala Police Act) and real Kerala Police FIR data. Training labels are derived automatically from the IPC/BNS section numbers present in the FIRs themselves — no external AI is used to generate training data.

For conversational legal Q&A, FirAI optionally integrates with Anthropic's Claude API. If no API key is configured, all legal questions are answered from the built-in structured knowledge base.

Custom Models

#	Model	Architecture	What It Does
1	FirClassifier	BiLSTM + Attention Neural Network	Crime type + severity classification
2	FirNER	Regex + Custom Extraction Pipeline	Entity extraction (names, locations, vehicles, amounts)
3	FirSummarizer	TextRank + Template Engine	English narrative summarization
4	FirLegalMapper	IPC/BNS Section Lookup + TF-IDF	IPC/BNS section prediction from acts data
5	FirLegalLLM	Claude API (optional) + Knowledge Base	Conversational Legal Q&A with RAG

Training Data & Context

90+ real Kerala Police FIRs (Malayalam narratives) from 10+ police stations across Kerala
Indian Legal Corpus — Comprehensive knowledge base with elements, punishments, bail status, and investigation steps for IPC, BNS, NDPS, POCSO, MVA, and Kerala Abkari Act sections
IPC to BNS Transition Map — Accurate cross-referencing between the Indian Penal Code (1860) and Bharatiya Nyaya Sanhita (2023)
Section-derived classification — Crime type and severity are derived deterministically from the actual IPC/BNS sections in each FIR, falling back to the neural classifier when no section data is available

Performance

Metric	Score
Crime classification accuracy	98.8%
Severity classification accuracy	98.8%
Model size	3.3 MB
Inference time	< 100ms on CPU
Internet required at runtime	No (Claude API is optional)

Architecture

┌──────────────────────────────────────────────────────────┐
│                     Docker Compose                       │
│                                                          │
│  ┌──────────┐    ┌──────────────────┐   ┌─────────────┐  │
│  │ Frontend │    │     Backend      │   │  PostgreSQL │  │
│  │  React   │◄──►│    FastAPI       │◄─►│     16      │  │
│  │  :3000   │    │    :8000         │   │   :5432     │  │
│  └──────────┘    └────────┬─────────┘   └─────────────┘  │
│                           │                              │
│              ┌────────────┼────────────┐                 │
│              ▼            ▼            ▼                 │
│          FirAI         Bhashini    Sentence              │
│          Engine          API      Transformers           │
│       (Custom AI)    (Translate)  (Embeddings)           │
│                           │                              │
│                    ┌──────▼──────┐                       │
│                    │  Claude API │ (optional)            │
│                    │  Legal Q&A  │                       │
│                    └─────────────┘                       │
└──────────────────────────────────────────────────────────┘

AI Pipeline

FIR Narrative (Malayalam/English)
        │
        ├──► Section-Derived Labeler ──► Crime Type + Severity (primary)
        ├──► FirClassifier (BiLSTM) ──── Crime Type + Severity (fallback)
        ├──► FirNER (Regex/Patterns) ──► Entities (names, vehicles, amounts)
        ├──► FirSummarizer (TextRank) ── English Summary
        ├──► FirLegalMapper ──────────── Applicable IPC/BNS Sections
        └──► Legal Corpus / Claude API ► Investigation Recommendations + Q&A

Prerequisites

Requirement	Notes
Docker Desktop	Includes Docker Engine + Docker Compose
Git	To clone the repository
Python 3.11+	Only needed if training the AI model locally
Anthropic API Key	Optional — enables AI-powered legal chat (free to start at console.anthropic.com)
Bhashini API Key	Optional — only needed for Malayalam translation

Minimum system: 4 GB RAM, 10 GB free disk space (for Docker images + ML models)

Step 1 — Install Docker

Docker Desktop bundles everything you need (Docker Engine + Docker Compose).

Windows

Download Docker Desktop from https://www.docker.com/products/docker-desktop/
Run the installer — accept defaults.
When prompted, enable WSL 2 (recommended).
Restart your computer after installation.
Open Docker Desktop from the Start menu. Wait for "Engine running" (green icon in taskbar).
Verify in PowerShell:
```
docker --version
docker compose version
```

macOS

Download Docker Desktop:
- Apple Silicon (M1/M2/M3): https://desktop.docker.com/mac/main/arm64/Docker.dmg
- Intel: https://desktop.docker.com/mac/main/amd64/Docker.dmg
Open the .dmg and drag Docker to Applications.
Launch Docker from Applications. Grant permissions if asked.
Verify in Terminal:
```
docker --version
docker compose version
```

Linux (Ubuntu / Debian)

sudo apt-get remove docker docker-engine docker.io containerd runc
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
sudo systemctl enable --now docker

Step 2 — Clone the Repository

git clone https://github.com/Ahamedshakir02/firai.git
cd firai

Don't have Git?

Windows: https://git-scm.com/download/win

macOS: xcode-select --install

Linux: sudo apt-get install git

Step 3 — Configure Environment

3a. Create your `.env` from the template

# Windows (PowerShell)
copy .env.example .env

# macOS / Linux
cp .env.example .env

This step is required. The project will not start without a .env file.

3b. Edit `.env`

# Windows
notepad .env

# macOS / Linux
nano .env

The default configuration works out of the box. The only value you need to add is an Anthropic API key if you want AI-powered legal chat:

# Database — leave unchanged, Docker handles it
POSTGRES_USER=firai
POSTGRES_PASSWORD=firai_secret
POSTGRES_DB=firai_db
DATABASE_URL=postgresql+asyncpg://firai:firai_secret@db:5432/firai_db

# Claude API — optional, enables AI-powered Legal Assistant
# Get your key at https://console.anthropic.com
ANTHROPIC_API_KEY=
CLAUDE_MODEL=claude-haiku-4-5-20251001

# Translation — optional, for Malayalam ↔ English
BHASHINI_API_KEY=
BHASHINI_USER_ID=

Without ANTHROPIC_API_KEY, the Legal Assistant still works — it answers queries from the built-in IPC/BNS knowledge base.

3c. Get an Anthropic API Key (optional)

Sign up at https://console.anthropic.com
Go to API Keys and create a new key
Paste it as ANTHROPIC_API_KEY=sk-ant-... in your .env

3d. Get a Bhashini API Key (optional, for translation)

Register at https://bhashini.gov.in/ulca/user-profile
Go to My Profile → API Keys
Copy your API Key and User ID into .env

Step 4 — Train the AI Model

FirAI includes a custom neural network that needs to be trained on the FIR data. Training takes ~5 minutes on CPU.

Option A: Train Locally

cd backend
pip install torch scikit-learn numpy
python training/train_classifier.py --epochs 50

Option B: Train on Google Colab (Free GPU)

Upload the backend/ folder to Colab

Run:

!pip install torch scikit-learn numpy
!python training/train_classifier.py --epochs 50 --data_dir ./data/structured

Download ai_engine/trained_models/classifier.pt and classifier_vocab.pkl

What Training Produces

ai_engine/trained_models/
├── classifier.pt          # 3.3 MB — trained neural network weights
└── classifier_vocab.pkl   # 32 KB — vocabulary (Malayalam + English tokens)

Pre-trained model included: The repository ships with a pre-trained model — you can skip this step and go straight to Step 5.

Step 5 — Run the Project

Make sure Docker Desktop is running, then from the project root:

docker compose up --build

What happens on first run

Step	What it does	Time
Build	Downloads base images, installs Python + npm packages	3–8 min
Database	PostgreSQL initialises with `firai_db`	~10 sec
Backend	FastAPI starts, loads AI models, seeds 90+ FIRs	1–2 min
Frontend	Vite dev server starts	~15 sec

Subsequent runs (without --build) start in under 30 seconds.

Running in detached mode

docker compose up --build -d

View logs:

docker compose logs -f           # all services
docker compose logs -f backend   # backend only
docker compose logs -f frontend  # frontend only

Stopping

docker compose down              # stops containers, keeps database
docker compose down -v           # stops containers and deletes database (fresh start)

Verify Everything Works

Service	URL	Expected
Dashboard	http://localhost:3000	Kerala Police FirAI dashboard
Backend API	http://localhost:8000/api/health	`{"status": "healthy"}`
API Docs	http://localhost:8000/docs	Interactive Swagger UI

You should see 90+ FIRs already loaded in the Case Intelligence page, sorted by real case numbers (e.g. Case 0008/2025).

Features

Feature	Page	Description
Authentication	`/login`	JWT-protected access with badge number + password login
Officer Profile	`/profile`	View officer details, admin panel for managing registration requests
Registration Portal	`/login` (register tab)	New officer registration with admin approval workflow
Dashboard	`/`	Crime stats, severity breakdown, monthly trends, recent FIRs
FIR Analyzer	`/fir-analyzer`	Upload a PDF or scanned image, or paste a narrative — AI classifies crime, extracts sections, suggests investigation steps
Case Intelligence	`/case-intelligence`	Browse and search FIRs by crime type and police station; multi-dimensional similarity search with PDF downloads
Legal Assistant	`/legal-assistant`	AI legal chat (Claude API or knowledge-base fallback), IPC ↔ BNS Cross-Mapper, multi-charge Punishment Calculator
MO Patterns	`/mo-patterns`	Detect recurring modus operandi across all FIR narratives
Translation	`/translation`	Translate FIR text between Malayalam and English

Project Structure

firai/
├── docker-compose.yml         # Orchestrates all 3 services
├── .env                       # Your config (never commit this)
├── .env.example               # Template for environment variables
│
├── backend/                   # Python / FastAPI
│   ├── Dockerfile
│   ├── main.py                # App entry point, startup hooks
│   ├── config.py              # Settings loaded from .env
│   ├── database.py            # SQLAlchemy async engine + session
│   ├── seed.py                # Seeds existing FIRs on first boot
│   ├── seed_officers.py       # Seeds demo officer accounts
│   ├── requirements.txt
│   ├── scripts/
│   │   ├── extract_rules.py       # Extract IPC/BNS sections from PDF law texts
│   │   ├── rename_firs.py         # Rename JSONs/PDFs to FIR_XXXX_YYYY_STATION format
│   │   └── reprocess_all_firs.py  # Wipe & re-OCR all PDFs (dedup + auto-name)
│   ├── ai_engine/             # Custom AI System
│   │   ├── data/
│   │   │   ├── label_generator.py   # Derives crime labels from IPC/BNS sections
│   │   │   ├── legal_corpus.py      # Indian law knowledge base (IPC, BNS, CrPC)
│   │   │   └── datasets/            # Generated training data
│   │   ├── models/
│   │   │   ├── classifier.py        # BiLSTM neural network architecture
│   │   │   └── legal_llm.py         # Claude API integration + knowledge-base fallback
│   │   ├── inference/               # Model loading & prediction
│   │   └── trained_models/          # Saved model weights
│   │       ├── classifier.pt        # Trained neural network (3.3 MB)
│   │       └── classifier_vocab.pkl # Vocabulary (32 KB)
│   ├── training/
│   │   └── train_classifier.py      # Training script (Colab/local)
│   ├── models/
│   │   ├── fir.py             # FIR, Accused, MOPattern, LegalSection ORM models
│   │   └── officer.py         # Officer, RegistrationRequest ORM models
│   ├── routers/
│   │   ├── auth.py            # JWT auth, registration, admin approval
│   │   ├── firs.py            # FIR upload, analysis, similarity, export
│   │   ├── dashboard.py       # Statistics endpoint
│   │   ├── legal.py           # Legal Q&A, section lookup, IPC↔BNS mapping
│   │   ├── mo_patterns.py     # MO pattern detection
│   │   └── translate.py       # Translation endpoint
│   ├── schemas/
│   │   └── fir.py             # Pydantic request/response schemas
│   ├── services/
│   │   ├── firai_engine.py    # Main AI service — classification, legal Q&A, MO detection
│   │   ├── embedding_engine.py# Sentence-Transformer similarity search
│   │   ├── fir_processor.py   # PDF OCR + field extraction + auto-naming
│   │   ├── bhashini_service.py# Malayalam translation (Bhashini + Google fallback)
│   │   ├── legal_kb.py        # IPC/BNS knowledge base service
│   │   └── mo_detector.py     # MO pattern detection logic
│   ├── storage/               # Runtime file storage
│   └── data/
│       ├── raw_pdfs/          # Original FIR PDF documents
│       ├── structured/        # Structured FIR JSON files
│       └── rules/             # Extracted legal rules (extracted_rules.json)
│
└── frontend/                  # React / Vite
    ├── Dockerfile
    ├── package.json
    └── src/
        ├── main.jsx           # App entry point
        ├── App.jsx            # Router setup + ProtectedRoute
        ├── index.css          # Global design system (dark theme, responsive)
        ├── api/
        │   └── client.js      # Axios API client (all endpoints + JWT interceptor)
        ├── context/
        │   └── AuthContext.jsx # Authentication context provider
        ├── components/
        │   └── Layout/
        │       ├── Layout.jsx  # App shell with mobile sidebar toggle
        │       ├── Sidebar.jsx # Navigation sidebar (slide-in on mobile)
        │       └── Header.jsx  # Top bar with hamburger menu on mobile
        └── pages/
            ├── Login.jsx
            ├── Profile.jsx
            ├── Dashboard.jsx
            ├── FIRAnalyzer.jsx
            ├── CaseIntelligence.jsx
            ├── LegalAssistant.jsx
            ├── MOPatterns.jsx
            └── Translation.jsx

Environment Variables

Variable	Required	Default	Description
`POSTGRES_USER`	Yes	`firai`	PostgreSQL username
`POSTGRES_PASSWORD`	Yes	`firai_secret`	PostgreSQL password
`POSTGRES_DB`	Yes	`firai_db`	Database name
`DATABASE_URL`	Yes	(see .env)	Full async connection string
`ANTHROPIC_API_KEY`	No	—	Claude API key — enables AI-powered legal chat
`CLAUDE_MODEL`	No	`claude-haiku-4-5-20251001`	Claude model to use for legal Q&A
`BHASHINI_API_KEY`	No	—	Bhashini API for Malayalam ↔ English translation
`BHASHINI_USER_ID`	No	—	Bhashini user ID
`GOOGLE_MAPS_API_KEY`	No	—	Reserved for future map integration

Without ANTHROPIC_API_KEY, legal queries are answered from the built-in IPC/BNS knowledge base — no functionality is lost, only conversational AI responses are unavailable.

API Endpoints

The full interactive API docs are at http://localhost:8000/docs when running.

Authentication (Public)

Endpoint	Method	Description
`/api/health`	`GET`	Health check with service status
`/api/auth/login`	`POST`	Authenticate officer — returns JWT
`/api/auth/register-request`	`POST`	Submit officer registration request

Authentication (Protected)

Endpoint	Method	Description
`/api/auth/me`	`GET`	Get current officer profile
`/api/auth/registration-requests`	`GET`	Admin: list all registration requests
`/api/auth/registration-requests/{id}/approve`	`POST`	Admin: approve a request
`/api/auth/registration-requests/{id}/reject`	`POST`	Admin: reject a request

FIRs (All protected)

Endpoint	Method	Description
`/api/firs`	`GET`	List FIRs — filter by `crime_type`, `police_station`, `severity`, `search`
`/api/firs/{id}`	`GET`	Full FIR details with accused
`/api/firs/{id}/download`	`GET`	Download FIR PDF (JSON fallback)
`/api/firs/{id}/similar`	`GET`	Find similar FIRs (embedding + accused matching)
`/api/firs/upload-pdf`	`POST`	Upload and analyse a single FIR PDF or scanned image (PNG/JPG/TIFF/BMP/WEBP)
`/api/firs/analyze-text`	`POST`	Analyse pasted narrative (no save)
`/api/firs/analyze-and-save`	`POST`	Analyse and save narrative as new FIR
`/api/firs/bulk-upload`	`POST`	Bulk upload multiple FIR PDFs or scanned images
`/api/firs/bulk-upload-json`	`POST`	Bulk upload pre-processed JSON files
`/api/firs/export/all`	`GET`	Export all FIRs as JSON

Legal Assistant (All protected)

Endpoint	Method	Description
`/api/legal/query`	`POST`	Ask a legal question (Claude API or KB fallback)
`/api/legal/sections`	`GET`	Browse IPC/BNS legal sections
`/api/legal/sections/{act}/{section}`	`GET`	Look up a specific section
`/api/legal/sections/lookup`	`POST`	Batch look up sections for a FIR's acts list
`/api/legal/equivalent/{act}/{section}`	`GET`	IPC ↔ BNS cross-mapping
`/api/legal/equivalent/batch`	`POST`	Batch IPC ↔ BNS cross-mapping
`/api/legal/punishment-calc`	`POST`	Punishment calculator for multiple sections

Other (All protected)

Endpoint	Method	Description
`/api/dashboard/stats`	`GET`	Aggregated dashboard statistics
`/api/mo/patterns`	`GET`	List detected MO patterns
`/api/mo/detect`	`POST`	Run MO detection across all FIRs
`/api/translate`	`POST`	Translate text (Malayalam ↔ English)

Common Issues & Fixes

`database "firai" does not exist`

Stale volume from a previous configuration:

docker compose down -v
docker compose up --build

`Failed to resolve import "../../api/client"`

Import path is wrong. All page files in src/pages/ should use one level up:

import { firAPI } from '../api/client';   // correct

`connection is closed` (SQLAlchemy)

Pool holds a stale connection after a DB restart. Handled automatically by pool_pre_ping=True. If it persists:

docker compose restart backend

Frontend shows a blank page or cached errors

Hard-refresh the browser:

Windows/Linux: Ctrl + Shift + R
macOS: Cmd + Shift + R

Or restart the frontend container:

docker compose restart frontend

PDF / image upload is slow

OCR of multi-page FIR PDFs (or large scanned images) uses Tesseract and takes 15–60 seconds per file — this is expected. The backend runs OCR in a background thread so the app stays responsive.

Similar-case results look wrong after upgrading

FirAI uses the multilingual paraphrase-multilingual-MiniLM-L12-v2 embedding model. If you upgraded from an older build that used all-MiniLM-L6-v2, the FIR vectors stored in your database were produced by the old model and won't match new queries. Re-seed so every narrative is re-embedded with the new model:

docker compose down -v
docker compose up --build

The new model (~470 MB) is downloaded once on first boot and cached for subsequent runs.

Docker Desktop — "WSL 2 installation is incomplete" (Windows)

Follow Microsoft's guide: https://aka.ms/wsl2kernel
Then restart Docker Desktop.

Legal Assistant returns knowledge-base answers instead of AI chat

The Claude API key is not configured. Add ANTHROPIC_API_KEY=sk-ant-... to your .env file and restart the backend:

docker compose restart backend

Tech Stack

Layer	Technology	Purpose
Frontend	React 19, Vite, React Router v7, Recharts, Lucide Icons, Axios	Responsive dashboard UI
Backend	Python 3.11, FastAPI 0.115, SQLAlchemy 2.0 (async), Pydantic v2, python-jose, passlib	REST API + JWT Auth
Database	PostgreSQL 16 (Alpine)	FIR storage + officer accounts
AI Engine	Custom BiLSTM + Attention (PyTorch CPU), trained on IPC/BNS legal corpus	Crime classification, entity extraction, legal mapping
Legal Q&A	Claude API (Anthropic) — optional; built-in IPC/BNS knowledge base as fallback	Conversational legal answers with RAG
Legal KB	Indian Legal Corpus (IPC, BNS, CrPC, BNSS, NDPS, POCSO, MVA, Kerala Abkari Act)	Section lookup, punishment calculator, investigation steps
Embeddings	`paraphrase-multilingual-MiniLM-L12-v2` (Sentence-Transformers)	Multilingual narrative similarity search (Malayalam + English)
OCR	PyMuPDF + Tesseract OCR (`mal+eng`)	PDF and image text extraction
Translation	Bhashini API (AI4Bharat) + Google Translate fallback (deep-translator)	Malayalam ↔ English
Containerisation	Docker, Docker Compose	One-command deployment

FIR File Management

All FIR files follow the naming convention: FIR_{number}_{year}_{station}

Scenario	What Happens
Upload via app	PDF or image is OCR'd, FIR number extracted, saved as `FIR_0517_2024_KALPAKANCHERRY.pdf` (images keep their original extension, e.g. `.png`)
Bulk upload	Each PDF/image auto-named based on extracted metadata
Database seed	JSON files auto-named with FIR number + station on first boot

Data Management Scripts

cd backend

# Extract IPC/BNS sections from law PDFs into extracted_rules.json
python scripts/extract_rules.py

# Rename existing files to standardized FIR names (dry run)
python scripts/rename_firs.py

# Apply renames
python scripts/rename_firs.py --apply

# Full reprocess: delete all JSONs, remove duplicates, re-OCR everything (dry run)
python scripts/reprocess_all_firs.py

# Apply reprocessing (requires Tesseract OCR)
python scripts/reprocess_all_firs.py --apply

Reprocessing requires Tesseract OCR with Malayalam language data:

Windows: winget install UB-Mannheim.TesseractOCR + download mal.traineddata

Docker: Already included in the Dockerfile

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit: git commit -m 'Add my feature'
Push: git push origin feature/my-feature
Open a Pull Request

Kerala AI Mission (K-AI) & Kerala Startup Mission

FirAI is developed for the Kerala AI Mission (K-AI) under the Kerala Startup Mission (KSUM) — Government of Kerala's flagship initiative to harness Artificial Intelligence for public good and smart governance.

Kerala Startup Mission (KSUM) — Established in 2006 and headquartered in Thiruvananthapuram, KSUM is the Government of Kerala's nodal agency for entrepreneurship development and technology business incubation, having supported 6,400+ startups across the state.
Kerala AI Mission (K-AI) — "The Guiding Hand of Smart Governance." A flagship programme (in collaboration with the Kerala State IT Mission and ICT Academy) that brings together government bodies, technology innovators, startups, researchers, and citizens to co-create AI solutions that are ethical, transparent, and people-centric — spanning health, education, agriculture, finance, transport, and law enforcement.

FirAI aligns directly with K-AI's mandate: applying NLP, OCR, and semantic AI to a real public-sector challenge — transforming unstructured FIR records into searchable, analyzable intelligence for Kerala Police.

FirAI is an independent project built in the context of the K-AI / KSUM programme. It is not an official Government of Kerala product, and references to KSUM/K-AI do not imply endorsement.

Learn more: Kerala Startup Mission · Kerala AI Mission

License

This project is licensed under the MIT License — see the LICENSE file for the full text.

Copyright (c) 2026 Ahamed Shakir — FirAI Project Contributors
Developed for the Kerala AI Mission (K-AI) under Kerala Startup Mission (KSUM).

You are free to use, copy, modify, and distribute this software with attribution. It is provided "as is", without warranty of any kind.

FirAI — Custom AI, Smarter Investigations, Safer Kerala
_{Built for the Kerala AI Mission (K-AI) · Kerala Startup Mission}

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
.idea		.idea
backend		backend
docs/screenshots		docs/screenshots
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPER_GUIDE.md		DEVELOPER_GUIDE.md
LICENSE		LICENSE
README.md		README.md
SETUP_LOCAL.md		SETUP_LOCAL.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

FirAI — Kerala Police AI Investigation Assistant

Table of Contents

Overview

Core Principle: Narrative-Centric

📸 Screenshots

FirAI Engine — Custom AI

How It Works

Custom Models

Training Data & Context

Performance

Architecture

AI Pipeline

Prerequisites

Step 1 — Install Docker

Windows

macOS

Linux (Ubuntu / Debian)

Step 2 — Clone the Repository

Step 3 — Configure Environment

3a. Create your .env from the template

3b. Edit .env

3c. Get an Anthropic API Key (optional)

3d. Get a Bhashini API Key (optional, for translation)

Step 4 — Train the AI Model

Option A: Train Locally

Option B: Train on Google Colab (Free GPU)

What Training Produces

Step 5 — Run the Project

What happens on first run

Running in detached mode

Stopping

Verify Everything Works

Features

Project Structure

Environment Variables

API Endpoints

Authentication (Public)

Authentication (Protected)

FIRs (All protected)

Legal Assistant (All protected)

Other (All protected)

Common Issues & Fixes

database "firai" does not exist

Failed to resolve import "../../api/client"

connection is closed (SQLAlchemy)

Frontend shows a blank page or cached errors

PDF / image upload is slow

Similar-case results look wrong after upgrading

Docker Desktop — "WSL 2 installation is incomplete" (Windows)

Legal Assistant returns knowledge-base answers instead of AI chat

Tech Stack

FIR File Management

Data Management Scripts

Contributing

Kerala AI Mission (K-AI) & Kerala Startup Mission

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

3a. Create your `.env` from the template

3b. Edit `.env`

`database "firai" does not exist`

`Failed to resolve import "../../api/client"`

`connection is closed` (SQLAlchemy)