Verdict-AI

Verdict-AI helps people review structured evidence, understand uncertainty, and decide what to do next. It combines model-based reasoning with deterministic safeguards and keeps the final decision in human hands.

Live Resources

Resource	Link
Live Application	verdict-ai-seven.vercel.app
Demo Video	Watch on YouTube
GitHub Repository	aadityakulkarni12-cell/Verdict-AI

Why Verdict-AI exists

Evidence-based decisions are rarely difficult because facts are completely absent. They are difficult because the available facts can conflict, carry different levels of importance, leave critical gaps, or support more than one reasonable interpretation. A recommendation without visible reasoning does little to help someone judge those tradeoffs.

Verdict-AI treats the process as an investigation. It normalizes an evidence package, evaluates individual findings, highlights contradictions and uncertainty, and recommends a concrete next action. The result includes the reasoning behind the recommendation so a person can inspect it rather than simply accept a model output.

GPT-5.6 is used for the part of the process that requires synthesis: comparing multiple findings, distinguishing uncertainty from contradiction, and explaining how the evidence supports a judgment. Its output is constrained to a typed contract and sits inside a broader pipeline with deterministic evaluation and fallback behavior.

Design principles

• Live GPT-5.6 reasoning: each investigation sends structured evidence through the backend decision pipeline. When GPT-5.6 produces the judgment, the interface identifies the source as AI Reasoning Engine (GPT-5.6).
• Deterministic fallback: if the API key is not configured, the provider is unavailable, or the model response fails validation, the investigation completes with a labeled, rule-based fallback instead of failing silently.
• Human in the loop: Verdict-AI explains evidence, confidence, uncertainty, and a recommended next action. A person remains responsible for the final decision.

Built with OpenAI

GPT-5.6 and the Responses API

GPT-5.6 is the reasoning engine behind Verdict-AI's AI Judge. The backend sends normalized evidence, an evaluation plan, and deterministic findings to the OpenAI Responses API. Pydantic Structured Outputs constrain the result to the application's judgment contract, including the verdict, rationale, confidence, uncertainty notes, and cited evidence. The API key and model call remain backend-only.

Codex

Codex was used throughout development to accelerate implementation, debugging, testing, documentation, and repository refinement. Its suggestions and changes were reviewed as part of the normal engineering process; product direction and final decisions remained human-owned.

Judge Quick Start

The fastest path is the live application. To run it locally, clone the repository and open two PowerShell terminals:

git clone https://github.com/aadityakulkarni12-cell/Verdict-AI.git
cd Verdict-AI

1. Start the backend

cd backend
Copy-Item .env.example .env
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
uvicorn app.main:app --reload

The backend starts at http://localhost:8000. Leaving OPENAI_API_KEY empty runs the deterministic fallback. For live GPT-5.6 reasoning, add your key to backend/.env:

OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-5.6
VERDICT_AI_JUDGE_ENABLED=true

Restart the backend after editing .env.

2. Start the frontend in a second terminal

cd frontend
Copy-Item .env.example .env.local
npm ci
npm run dev

Open http://localhost:5173, select a scenario, and click Investigate. The result clearly labels whether GPT-5.6 or the deterministic fallback produced the judgment.

Prerequisites

• Python 3.11 or newer
• Node.js 20 or newer
• npm (included with Node.js)
• Git
• An OpenAI Platform account and API key for live GPT-5.6 reasoning; the project still runs in deterministic mode without a key

Get an OpenAI API key

1. Sign in to the OpenAI Platform.
2. Open the API keys page and create a secret key.
3. Copy backend/.env.example to backend/.env and set OPENAI_API_KEY there.

Keep the key private. Never commit backend/.env or place the key in a VITE_* frontend variable, because Vite variables are included in browser assets. API usage may require billing to be configured on the OpenAI Platform account.

How the decision flow works

1. The user selects or supplies a structured evidence package.
2. The deterministic pipeline normalizes the evidence, creates an evaluation plan, and produces findings and confidence diagnostics.
3. GPT-5.6 reviews that context and returns a validated structured judgment through the Responses API.
4. If live AI is unavailable or invalid, the deterministic Judge returns a labeled fallback judgment.
5. Verdict-AI presents the reasoning, uncertainty, recommendation, and next action for human review.

The decision pipeline is documented in DECISION_ENGINE.md, AI behavior in AI_JUDGE.md, and system boundaries in ARCHITECTURE.md.

Project structure

Verdict-AI/
|-- frontend/   # React + TypeScript + Vite experience
|-- backend/    # FastAPI decision pipeline and OpenAI integration
|-- AI_JUDGE.md
|-- ARCHITECTURE.md
|-- DECISION_ENGINE.md
`-- README.md

Useful local URLs

• Frontend: http://localhost:5173
• API: http://localhost:8000
• Health check: http://localhost:8000/health
• Interactive API docs: http://localhost:8000/docs

Deploy to Vercel

Verdict-AI deploys from the same GitHub repository as two Vercel projects: one rooted at backend/ and one at frontend/.

1. Deploy the backend

Import the repository in Vercel and configure:

• Root Directory: backend
• Framework/build settings: use Vercel's detected defaults
• Environment variables:

Name	Value	Required
OPENAI_API_KEY	Your OpenAI project key	No; omit for deterministic mode
OPENAI_MODEL	gpt-5.6	No; this is the configured default
VERDICT_AI_JUDGE_ENABLED	true	Yes
VERDICT_ENVIRONMENT	production	Recommended
VERDICT_CORS_ORIGINS	Frontend URL or planned domain	Yes

backend/index.py exposes the FastAPI application to Vercel's Python runtime. After deployment, verify the service using its assigned URL:

Invoke-RestMethod "https://YOUR-BACKEND.vercel.app/health"

Expected response:

{"status":"ok","service":"verdict-ai-api","version":"0.1.0"}

2. Deploy the frontend

Import the same repository as a second Vercel project and configure:

• Root Directory: frontend
• Framework Preset: Vite
• Environment variable:

VITE_API_BASE_URL=https://YOUR-BACKEND.vercel.app

frontend/vercel.json defines the production output and preserves React routes during direct navigation.

3. Finalize CORS and validate

Set VERDICT_CORS_ORIGINS in the backend project to the exact frontend URL without a trailing slash, then redeploy the backend:

VERDICT_CORS_ORIGINS=https://YOUR-FRONTEND.vercel.app

Use comma-separated values for multiple trusted domains. Do not use * in production. Confirm the backend health check, open the frontend, and directly visit /evidence, /decisions, and /settings to verify client-side routing.

Once both Vercel projects are connected to GitHub, pushes create deployments automatically. The GitHub Actions workflow runs backend tests and the frontend production build; Vercel handles deployment.

Verify before pushing

cd backend
python -m pytest

cd ..\frontend
npm ci
npm run build

Project scope

• The synthetic scenarios use fictional evidence and exercise the live backend pipeline.
• POST /evaluate runs the decision pipeline; GET /decision/{id} returns an in-memory or seeded decision.
• The in-memory backend store may reset between serverless invocations.
• Authentication, persistent storage, and domain-specific production policy are not included in the current project scope.

Contributing

Contributions and feedback are welcome. Open an issue to report a problem or suggest an improvement, or submit a pull request with a focused change. If you are considering a larger change, starting with an issue helps align the approach before implementation.