Civic Navigator

An AI agent that files consumer complaints on government portals — so you don't have to.

Currently live with Singapore's CASE portal. Every complaint filed is real.

The Problem • The Solution • How It Works • Architecture • Tech Stack • Getting Started • Features • CASE Coverage • Limitations

---

The Problem

Most consumers never escalate bad experiences into formal complaints.

In practice, this is a form-friction problem:

• Long multi-step forms with strict field rules.
• Unclear categories and legal wording.
• Time cost of figuring out the right portal and evidence format.
• Fear of making mistakes that invalidate submissions.

A commonly cited behavior pattern is that roughly 96% of dissatisfied consumers do not file formal complaints. They abandon the process before submission.

The Solution

Civic Navigator turns complaint filing into a guided chat + autonomous filing workflow:

• Users describe what happened in natural language.
• A GPT-4 intake agent collects mandatory CASE fields conversationally.
• A TinyFish browser agent opens the real CASE complaint portal at http://crdcomplaints.azurewebsites.net/, navigates the 4-step form, fills fields, handles declaration consent, and submits.
• Users receive a real confirmation/case number and confirmation email sent by CASE.
• While filing runs, users get live status updates and a gamified consumer-rights quiz.

This is not a simulation. It files complaints on the live CASE complaint system.

The intake logic and portal-specific logic are separated by design. Extending Civic Navigator to other government complaint portals means adding a new adapter — not rebuilding the system.

How It Works

+------------------+      +------------------+      +-----------------------+      +-------------------+      +-------------------------+
| User Chat Input  | ---> | GPT-4 Intake Bot | ---> | TinyFish Browser Agent| ---> | CASE Web Portal   | ---> | Confirmation + Email    |
| (Natural Language)|     | (Field Collection)|      | (4-Step Form Filing)  |      | (Real Submission) |      | (Real CASE Response)    |
+------------------+      +------------------+      +-----------------------+      +-------------------+      +-------------------------+

Architecture

                                +----------------------+
                                |      OpenAI GPT-4    |
                                |  Intake + Validation |
                                +----------+-----------+
                                           ^
                                           |
+----------------------+       +-----------+-----------+       +-------------------------+
| Frontend (HTML/CSS/JS)| <--> | FastAPI Backend       | <-->  | TinyFish Browser Agent |
| Chat + SSE + Quiz     |      |                       |       | (Web Automation)       |
+----------+-----------+       +-----------+-----------+       +------------+------------+
           ^                               |                                |
           |                               |                                v
           +-------------------------------+------------------------> +---------------------+
                                                                     | CASE Complaint Portal|
                                                                     | crdcomplaints...     |
                                                                     +---------------------+

Tech Stack

Component	Technology	Purpose
Backend API	FastAPI (Python 3.11)	Routes, orchestration, SSE status streaming
LLM Intake	OpenAI GPT-4	Conversational field collection + structured extraction
Browser Automation	TinyFish Agent API	End-to-end complaint filing in real portal
Frontend	Vanilla HTML/CSS/JS	Chat UI, verification UI, live status + quiz
Streaming	Server-Sent Events (SSE)	Real-time filing progress updates
Testing	Pytest	Backend validation and regression checks

Getting Started

Prerequisites

• Python 3.11+
• pip
• OpenAI API key
• TinyFish API key

Installation

git clone https://github.com/13shreyansh/civic-navigator.git
cd civic-navigator

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -r requirements.txt
cp .env.example .env

Update .env:

OPENAI_API_KEY=your_openai_api_key_here
TINYFISH_API_KEY=your_tinyfish_api_key_here

Run

uvicorn app:app --reload --port 8000

Open: http://127.0.0.1:8000

Run Tests

pytest tests/ -v

Project Structure

civic-navigator/
├── agent/
│   ├── __init__.py
│   ├── intake.py          # GPT-4 conversational intake logic
│   ├── router.py          # Complaint routing logic
│   └── executor.py        # TinyFish filing goal + SSE integration
├── templates/
│   ├── index.html         # Intake chat interface
│   ├── verify.html        # User review/edit before filing
│   └── status.html        # Live filing tracker + quiz
├── static/
├── tests/
│   └── __init__.py
├── app.py
├── requirements.txt
├── .env.example
├── .gitignore
├── LICENSE
└── README.md

Key Features

• Natural-language complaint intake.
• Smart mandatory-field mapping for CASE complaint forms.
• Real-time filing progress with SSE.
• In-flow consumer-rights quiz with streak gamification.
• Real submission with real CASE confirmation response.
• Format-aware validation (NRIC fragment, date format, phone normalization, etc.).

CASE Form Coverage

CASE Step	Form Area	Civic Navigator Coverage
Step 1	Personal Particulars	Salutation, names, NRIC fragment, gender, DOB year, contact, address
Step 2	Vendor Address	Vendor name + address lookup fallback for mandatory vendor address fields
Step 3	Complaint Information	Nature/industry selection, transaction metadata, desired outcome, summary
Step 4	Declaration	Mandatory consent check + final submission

Limitations

• Scope is currently Singapore-focused (CASE filing flow).
• Typical filing run time is ~3-6 minutes depending on portal latency.
• Vendor address may require auto-research fallback when not provided by user.
• Browser automation behavior depends on portal UI stability.

Built For

Built at the OpenAI Hackathon Singapore 2025. Government complaint systems are broken everywhere, not just in Singapore. The approach behind Civic Navigator — AI agents that navigate bureaucracy on behalf of citizens — is not limited to one portal or one country. We believe this is how consumer protection should work.

License

Distributed under the MIT License. See LICENSE.