diff --git a/README.md b/README.md index 9d451b3..4f21713 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,167 @@ -# ARAI — Legal Mediation Assistant +# ARAI — AI-Powered Legal Mediation Assistant -A web application built in **48 hours** at a legal-tech hackathon that helps users resolve disputes through mediation instead of court. +> Full-stack web application that leverages **GPT-4** to help Polish citizens resolve legal disputes through mediation instead of costly court proceedings. Built in **48 hours** at a legal-tech hackathon. -Describe your case in plain language, and the app will: +[![Angular](https://img.shields.io/badge/Angular-17-DD0031?logo=angular)](https://angular.io/) +[![Python](https://img.shields.io/badge/Python-3.x-3776AB?logo=python)](https://python.org/) +[![Flask](https://img.shields.io/badge/Flask-REST%20API-000000?logo=flask)](https://flask.palletsprojects.com/) +[![OpenAI](https://img.shields.io/badge/OpenAI-GPT--4-412991?logo=openai)](https://openai.com/) +[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) -1. **Categorise** the dispute (civil, labour, commercial, etc.) -2. **Estimate** the likely court cost and duration based on real court statistics -3. **Score and recommend** mediators suited to the case +--- + +## Overview + +Navigating the Polish legal system is complex and expensive. **ARAI** simplifies the process by allowing users to describe their dispute in plain language, then automatically: + +1. **Classifies the case** into 20+ legal categories (civil, labour, commercial, IP, family, etc.) using GPT-4 +2. **Estimates court costs and duration** based on real statistical data from Polish district and regional courts +3. **Recommends and ranks mediators** best suited for the case using a custom AI scoring algorithm +4. **Enables direct contact** with chosen mediators through the platform + +The goal is to reduce the burden on courts by directing eligible disputes toward mediation — a faster, cheaper, and less adversarial resolution path. + +--- + +## Key Features + +| Feature | Description | +|---|---| +| **Natural Language Case Input** | Users describe their legal problem in free-form Polish text — no legal knowledge required | +| **AI Case Categorization** | GPT-4 classifies the dispute across 20+ legal domains (IP, labour, family, real estate, etc.) | +| **Court Cost Estimation** | Calculates expected court fees, attorney costs, and expert witness expenses using official Polish fee schedules | +| **Trial Duration Prediction** | Estimates case length in months using real court statistics (district vs. regional courts) | +| **Mediator Matching** | Ranks mediators by specialization overlap, AI compatibility score, user ratings, and price | +| **Multi-Step Wizard UI** | Guided 3-screen flow: Case Input → Cost Overview → Mediator Recommendations | + +--- + +## Architecture + +``` +┌──────────────────────┐ HTTP/JSON ┌──────────────────────┐ +│ │ ──────────────────────► │ │ +│ Angular 17 SPA │ │ Flask REST API │ +│ (Material Design) │ ◄────────────────────── │ (Python) │ +│ │ │ │ +└──────────────────────┘ └──────┬───────────────┘ + Port 4200 │ + • Case input form ├── GPT-4 API + • Cost visualization │ (case classification + • Mediator cards │ & scoring) + • Email contact modal │ + ├── pandas +┌──────────────────────┐ │ (court statistics +│ WebSocket Relay │ │ from Excel data) +│ (Node.js) │ │ +│ Port 8080 │ └── Mediator DB +└──────────────────────┘ (scoring engine) +``` + +--- ## Tech Stack -| Layer | Technology | +| Layer | Technologies | |---|---| -| Frontend | Angular 17, Angular Material, SCSS | -| Backend | Python, Flask, pandas | -| AI | OpenAI API (case categorisation & mediator scoring) | -| Real-time | WebSocket relay (Node.js) | +| **Frontend** | Angular 17, Angular Material, RxJS, SCSS, TypeScript | +| **Backend** | Python 3, Flask, Flask-CORS, pandas, openpyxl | +| **AI / NLP** | OpenAI GPT-4 (case categorization, legal classification, mediator relevance scoring) | +| **Real-time** | WebSocket relay server (Node.js, `ws` library) | +| **Data** | Polish court statistics (Excel), official court fee schedules | +| **Build Tools** | Angular CLI, pnpm, pip | + +--- ## Project Structure ``` -arai-frontend/ Angular SPA — form wizard, results display, Material UI -Backend_correct/ Flask API — categorisation, cost estimation, mediator scoring -simple-ws/ Lightweight WebSocket relay server (Node.js) -statystyki/ Court statistics data pipeline (pandas + Excel) -franek/ ML experiments — case scoring prototypes +ARAI/ +├── arai-frontend/ # Angular 17 SPA — form wizard, results display, Material UI +│ └── src/app/ +│ ├── case-input/ # Main form: case description, trial value, location, toggles +│ ├── cost-view/ # Court cost and duration estimate display +│ ├── mediators-list/ # Ranked mediator cards with ratings and contact +│ ├── email-input/ # Modal dialog for contacting a mediator +│ ├── backend.service # HTTP client for Flask API communication +│ ├── koszta.service # Shared state for cost/duration data between views +│ └── mediatorzy.service # Shared state for mediator list between views +│ +├── Backend_correct/ # Flask REST API — orchestrates the full pipeline +│ └── app.py # POST / → categorize → estimate costs → score mediators +│ +├── simple-ws/ # Lightweight WebSocket relay server (Node.js) +│ └── ws.js +│ +├── statystyki/ # Court statistics data pipeline (pandas + Excel) +│ └── load_data.py # CLI tool for cost estimation from court data +│ +├── franek/ # ML experimentation — scoring prototypes and iteration +│ ├── scoring_final_final_2.py +│ ├── kategoryzacja_spraw.py +│ └── scoring.py +│ +└── example_input.txt # Sample case description for testing ``` -## Quick Start +--- + +## How It Works + +### 1. User Submits a Case + +The Angular frontend presents a form where the user provides: +- **Case description** in plain Polish (e.g., *"pracodawca nie wypłacił mi wynagrodzenia za ostatnie 2 miesiące i mnie zwolnił"*) +- **Dispute value** (PLN) — used to calculate court fees +- **Location** — for mediator proximity matching +- **Toggles** — whether expert witnesses or regular witnesses are involved + +### 2. AI Categorizes the Dispute + +The backend sends the case description to GPT-4, which classifies it across **20+ legal categories**: + +> Copyright & IP, Banking, Child Custody, Inheritance, Property Division, Civil Contracts, Employment, Business, Tenancy, Real Estate, Personal Rights, Civil Law, Labour Law, Commercial Law, Health & Safety, Debt Collection, Damages, Consumer Protection, Mobbing, Traffic Accidents, and more. + +Each category receives a binary relevance score (0 or 1), forming a **category vector** for the case. + +### 3. Court Cost Estimation + +Using official Polish fee schedules and real court statistics, the system calculates: +- **Court filing fees** — based on dispute value brackets (30 PLN – 20,000 PLN) +- **Attorney fees** — statutory rates based on dispute value +- **Expert witness costs** — average expert fee (~1,789 PLN) if applicable +- **Expected duration** — average case length in months from court statistical data + +### 4. Mediator Ranking + +Each mediator in the database has a profile with: +- Legal specializations (matching the 20+ category vector) +- Location and availability (in-person / online) +- User ratings and number of opinions +- Price per session + +The scoring engine computes a **composite score** by comparing the case's category vector against each mediator's expertise vector, weighted by AI confidence and user ratings. The top matches are returned as ranked recommendations. + +### 5. Results & Contact + +The user sees the estimated cost/duration and a ranked list of mediator cards. Each card shows the mediator's specialization, rating, price, and location. A **"Schedule Appointment"** button opens a contact dialog. + +--- + +## Getting Started + +### Prerequisites + +- **Python 3.8+** with pip +- **Node.js 18+** with pnpm +- **OpenAI API access** (or compatible endpoint) ### Backend ```bash cd Backend_correct -pip install flask flask-cors pandas openpyxl openai -python app.py +pip install flask flask-cors pandas openpyxl openai requests +python app.py # starts on http://localhost:5000 ``` ### Frontend @@ -42,17 +169,75 @@ python app.py ```bash cd arai-frontend pnpm install -pnpm start # serves on http://localhost:4200 +pnpm start # serves on http://localhost:4200 ``` The frontend proxies API requests to the Flask backend via `proxy.conf.json`. -## Team +### WebSocket Server (optional) -Built by 5 contributors during the hackathon: +```bash +cd simple-ws +pnpm install +node ws.js # runs on ws://localhost:8080 +``` -- Krzysztof Rudnicki — frontend & integration -- Franciszek Michalowski — ML & scoring -- Jakub Jarzembowski — backend -- Mateusz Szpyruk — data & statistics -- + 1 contributor +--- + +## API + +### `POST /` + +Accepts a case description and returns cost estimates + ranked mediators. + +**Request:** +```json +{ + "request_type": "user_input", + "request_data": { + "generic_input": "pracodawca nie wypłacił mi wynagrodzenia...", + "trial_value": 1000, + "location": "Warszawa", + "experts_called": false, + "witnesses_called": false + } +} +``` + +**Response:** +```json +{ + "response_type": "recommended_mediators", + "response_data": { + "first": { + "cost_of_trial": 390, + "time_of_trial": 8 + }, + "second": [ + { + "name": "Emilia Borek", + "specialization": "Prawo cywilne", + "localization": "Warszawa", + "street": "ul. Chmielna", + "online": "Tak", + "ai_rating": 0.62, + "user_rating": 1, + "number_of_opinions": 35, + "price": 100 + } + ] + } +} +``` + +--- + +## Skills Demonstrated + +- **Full-Stack Development** — Angular 17 SPA with TypeScript + Python Flask REST API +- **AI/LLM Integration** — GPT-4 prompt engineering for multi-label legal classification +- **Data Engineering** — pandas pipelines processing real court statistics from Excel sources +- **Algorithm Design** — Custom scoring engine combining AI classification vectors with mediator expertise profiles +- **UI/UX Design** — Multi-step wizard with Angular Material, responsive layout, dialog modals +- **API Design** — RESTful JSON API with structured request/response contracts and TypeScript interfaces +- **Rapid Prototyping** — Complete working product delivered in 48 hours with a 5-person team