⚖️ WhatLawSays

Unlike basic RAG chatbots that perform naive similarity searches and generate unchecked responses, WhatLawSays implements a strict, multi-agent deductive reasoning pipeline:

• 🧠 Immutable Fact Contracts (established_facts vs user_allegations vs unknown_facts):
  • Strictly separates objective, undisputed facts from subjective user allegations and indeterminate unknowns.
  • Enforces the core legal reasoning rule: $\text{UNKNOWN} \neq \text{FALSE}$ and $\text{UNKNOWN} \neq \text{TRUE}$.
• 🎯 Fact-Clean Legal Query Generator:
  • Generates retrieval queries strictly using explicit scenario terms without injecting premature section numbers or assumptions.
• 🔍 Expanded Hybrid Retrieval (Dense + Sparse BM25):
  • Executes parallel Dense Cosine (bge-small-en-v1.5) and Sparse BM25 (Qdrant/bm25) vector search over Qdrant, merged via Reciprocal Rank Fusion (RRF).
  • Unfiltered retrieval recall across full statutory corpus prevents premature category classification failures.
• ⚖️ Element-Based Verification & Statutory Exception Evaluation:
  • Verification Agent acts as a two-part logic judge: audits factual alignment first, then audits statutory accuracy.
  • Evaluates section-specific statutory exceptions (e.g. Grave & Sudden Provocation) and general legal defences (e.g. Right of Private Defence BNS Sec 38–44).
  • Automatically exonerates accused parties if statutory elements are CONTRADICTED_BY_FACT (e.g. valid invitation negates criminal trespass).
• 📋 Procedural Classification & Evidentiary Mapping (BNSS & BSS):
  • Automatically classifies offenses by Cognizability, Bailability, and Punishment Severity (CAPITAL_LIFE, SERIOUS, MINOR).
  • Maps procedural provisions under BNSS 2023 (e.g. Sec 173 e-FIR, Sec 185 search rules) and evidentiary standards under BSS 2023 (Sec 63 electronic records certificate).
• 🚨 Actionable Citizen Guidance & Statutory Reporting Duties:
  • Generates prioritized immediate action steps (emergency helpline 112, filing e-FIR, medical audit, digital evidence preservation).
  • Highlights statutory duties required of citizens under Indian criminal procedure (e.g. BNSS Section 33 obligation to report certain offenses).
• 🛡️ System UNDETERMINED State:
  • Returns a grounded legal explanation when facts are insufficient to establish an offense instead of making false claims.

├── frontend/
│   ├── app.py                   # Streamlit Interactive Web Application
│   ├── components.py            # Streamlit UI Components, Styling & Cards
│   └── sample_scenarios.py      # Predefined Legal Test Scenarios
├── src/
│   ├── main.py                  # FastAPI Application Gateway & Middleware
│   ├── config.py                # Pydantic Settings & Environment Configurations
│   ├── agents/
│   │   ├── graph.py             # LangGraph Multi-Agent Workflow Definition
│   │   ├── state.py             # TypedDict GraphState Engine Representation
│   │   └── nodes/
│   │       ├── extractor.py     # Agent 1: Established & Allegation Fact Extractor
│   │       ├── query_builder.py # Agent 2: Fact-Clean Query Generator
│   │       ├── retriever.py     # Hybrid Qdrant Vector Retriever Node
│   │       ├── reranker_node.py # Step 3: Legal Reranker Node
│   │       ├── analyst.py       # Agent 3: Deductive Analyst, Exceptions & Action Mapper
│   │       ├── verifier.py      # Agent 4: Claim-Evidence & Exception Verification Judge
│   │       └── compiler.py      # Step 5: Response Compiler & Calibrated Confidence
│   ├── core/
│   │   ├── vector_store.py      # Qdrant Client Hybrid Dense + BM25 Integration
│   │   ├── reranker.py          # Reranking Engine & Fallback Manager
│   │   ├── task_queue.py        # Redis Async Task Queue Producer/Consumer
│   │   ├── database.py          # SQLAlchemy PostgreSQL Async Models & Operations
│   │   └── logger.py            # Colorized Pipeline Stage Logging Engine
│   └── schemas/
│       ├── legal.py             # Pydantic Schemas for Requests, Offenses, Actions & Duties
│       └── corpus.py            # Legal Section Data Schemas
├── scripts/
│   ├── ingest_legal_corpus.py   # Seed Data Ingestion Script (Batch & Async Setup)
│   ├── test_pipeline.py         # End-to-End Pipeline Integration Test
│   ├── test_hybrid_search.py   # Hybrid Vector Search Verification Script
│   └── test_president_invitation.py # Test Script for Undetermined Scenario
├── tests/
│   └── test_agents.py           # Pytest Suite for Agents & Workflows
├── docker-compose.yml           # Multi-Container Deployment (FastAPI, Redis, Qdrant)
├── pyproject.toml               # Dependencies & UV Project Configuration
└── README.md                    # System Documentation

• Python 3.13+
• Docker & Docker Compose (for Qdrant & Redis)
• uv package manager (pip install uv)

git clone https://github.com/your-username/whatLawSays.git
cd whatLawSays
uv sync

Create a .env file in the root directory:

PROJECT_NAME="WhatLawSays Backend"
API_V1_STR="/api/v1"
GROQ_API_KEY="gsk_your_groq_api_key_here"
GROQ_MODEL="openai/gpt-oss-120b"
QDRANT_URL="http://localhost:6333"
REDIS_URL="redis://localhost:6379/0"
DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/whatlawsays"

docker-compose up -d

uv run python -m scripts.ingest_legal_corpus

uv run uvicorn src.main:app --reload --port 8000

Interactive API Documentation will be available at: http://localhost:8000/docs

uv run streamlit run frontend/app.py

Interactive Web Workbench will open at: http://localhost:8501

Run the automated agent pytest suite:

uv run pytest tests/

Run the hybrid search verification script:

uv run python -m scripts.test_hybrid_search

Run the President's Residence Invitation integration test:

uv run python -m scripts.test_president_invitation

POST /api/v1/analyze

{
  "scenario_text": "A person was going to enter the President's residence with an invitation to attend a party.",
  "jurisdiction": "India"
}

{
  "status": "UNDETERMINED",
  "scenario_domain": "POTENTIAL_CRIMINAL",
  "offense_status": "UNDETERMINED",
  "confidence_score": 0.35,
  "reason": "The supplied facts do not establish the elements of an offence.",
  "extracted_facts": {
    "explicit_facts": [
      "A person was going to enter the President's residence",
      "The person had an invitation to attend a party"
    ],
    "established_facts": [
      "The person possessed an invitation to attend a party at the President's residence"
    ],
    "user_allegations": [],
    "unknown_facts": [
      "Whether the person actually entered the residence",
      "Whether the invitation was valid or authorized"
    ],
    "actor": "person",
    "action": "enter",
    "scenario_domain": "POTENTIAL_CRIMINAL",
    "offense_status": "UNDETERMINED"
  },
  "identified_offenses": [],
  "applied_defences": [],
  "procedural_provisions": [
    "BNSS 2023 Section 173 - Procedure for recording information regarding cognizable offences"
  ],
  "immediate_action_steps": [
    {
      "step_number": 1,
      "title": "Verify Authorization",
      "action_details": "Confirm invitation authenticity with the event organizers or venue security prior to entry.",
      "statutory_duty_reference": null,
      "urgency": "MEDIUM"
    }
  ],
  "citizen_duties": [],
  "clarification_questions": [
    "Whether the person actually entered the residence",
    "Whether the invitation was valid or authorized"
  ],
  "disclaimer": "This platform provides legal information based on BNS/BNSS/BSS, not formal legal advice."
}

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