The Problem

Legal teams at the International Criminal Court must manually sift through large, multimodal evidence packages (PDFs, images, video, audio). The process is time‑consuming, error‑prone, and lacks a unified interface for AI‑assisted extraction and description.

What This Does

The repository delivers a full‑stack platform that lets users upload evidence through a React/TypeScript UI (apps/frontend/src/App.tsx and associated components) and have the content processed by a FastAPI backend (apps/backend/fast_api_backend.py). Core AI work lives in Python agents such as libs/icc-automation/evidence_analysis_agent.py (comprehensive evidence analysis) and libs/icc-automation/metadata_extraction_agent.py (metadata extraction). The Groq API supplies LLM inference, while optional Google Vision, HuggingFace, and Roboflow services handle multimodal perception. Dockerfiles in docker/ containerize the whole stack for production.

How It Is Wired

Execution begins in the frontend entry point apps/frontend/src/App.tsx. The app renders AgenticDashboard (most‑connected UI module) which uses UI primitives (ui/button, ui/card) and the ChatWidget for real‑time status. User file uploads are captured by FileUploadArea and sent via fetch to the FastAPI service at /analyze.

The backend entry point is the FastAPI app defined in apps/backend/fast_api_backend.py. The route POST /analyze calls analyze_evidence which instantiates libs/icc-automation/evidence_analysis_agent.EvidenceAnalysisAgent. That agent’s analyze_evidence_comprehensive orchestrates:

  1. Metadata extraction – calls metadata_extraction_agent.MetadataExtractionAgent.extract_comprehensive_metadata.
  2. Content analysis – invokes _analyze_content_with_ai, which builds a Groq request using the primary model (deepseek‑r1‑distill‑llama‑70b) and falls back to llama‑3.3‑70b‑versatile on failure.
  3. Result packaging – returns a JSON payload that the React dashboard displays.

The widest blast‑radius modules are apps/frontend/src/components/AgenticDashboard.tsx (imports three UI components and makes the API call) and libs/icc-automation/evidence_analysis_agent.py (contains 33 functions and a class; any change here can affect all downstream agents). No circular imports were detected, but deep nesting (up to 7 levels) in these modules raises cognitive load.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/ICCLexAI.git
cd ICCLexAI

# Backend setup (Python 3.9+)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt   # pulls FastAPI, Groq SDK, etc.

# Set required env vars (see README)
export GROQ_API_KEY=your_key
export STREAMLIT_SERVER_PORT=8501   # used only by legacy Streamlit front‑end
export STREAMLIT_SERVER_ADDRESS=0.0.0.0

# Start FastAPI backend
uvicorn apps.backend.fast_api_backend:app --host 0.0.0.0 --port 8000

# Front‑end setup (Node)
cd apps/frontend
npm ci               # uses package-lock.json
npm run dev          # Vite dev server, entry App.tsx

For containerised deployment, build the multi‑stage image:

docker build -f docker/Dockerfile -t icclexai .
docker run -p 8000:8000 -p 5173:5173 -e GROQ_API_KEY=$GROQ_API_KEY icclexai

Real‑World Use

A prosecutor uploads a zip containing PDF filings, a surveillance video, and EXIF‑rich photos. The UI shows upload progress, then streams back AI‑generated summaries and extracted GPS timestamps. The backend stores no persistent data; results are returned to the user session for immediate incorporation into ICC submission forms.

Code Health & Issues

  • High – cognitive_load – Deep nesting (max depth 7) in apps/frontend/src/components/AgenticDashboard.tsx, apps/agentic-ui/agentic_icc_app.py, libs/icc-automation/evidence_analysis_agent.py.
  • Medium – resource_safety – Files opened without a context manager in apps/agentic-ui/agentic_icc_app.py and libs/icc-automation/metadata_extraction_agent.py.
  • Medium – clarity – Repeated 6‑line code blocks across six files (e.g., similar error‑handling in agents).
  • Medium – resilience – Broad except: clauses in several agents, swallowing unexpected errors.
  • Medium – cognitive_load – Oversized files (agentic_icc_app.py, evidence_analysis_agent.py > 900 LOC) hindering maintainability.

All findings stem from deterministic static analysis; no additional issues were inferred. The repo includes a test file, CI workflow (.github/workflows/deploy.yml), Dockerfiles, a LICENSE, and lockfiles, indicating basic production hygiene.

The Bottom Line

ICCLexAI provides a functional, container‑ready stack that connects a modern React UI to a FastAPI‑backed AI pipeline for legal evidence analysis. Code quality suffers from deep nesting, oversized modules, and generic error handling, which will increase change‑impact risk. Teams comfortable with Python/FastAPI and React can adopt it quickly, but should refactor the high‑impact modules before extensive customization.