idea198-civicswarm-privacy-preserving/README.md

CivicSwarm

Privacy-preserving neighborhood deliberation router for participatory politics.

What It Does

CivicSwarm stores proposals, comments, resident profiles, preference signals, and deliberation ledger entries in SQLite. It then:

• clusters comments with TF-IDF + KMeans
• summarizes discussion by detected language
• routes proposal fragments to relevant residents by geography, interests, experience, and language
• aggregates preferences with optional differential-privacy noise
• exports a civic brief with provenance and audit trail

Stack

• Python 3.11
• FastAPI
• SQLAlchemy Core + SQLite
• scikit-learn
• langdetect

Install

python3 -m pip install -e .

For development:

python3 -m pip install -e ".[dev]"

Run

python -m civicswarm

Environment variables:

• CIVICSWARM_DB_PATH defaults to civicswarm.sqlite
• CIVICSWARM_HOST defaults to 127.0.0.1
• CIVICSWARM_PORT defaults to 8000

API

• POST /proposals
• POST /residents
• POST /proposals/{proposal_id}/comments
• POST /proposals/{proposal_id}/preferences
• GET /proposals/{proposal_id}/route
• GET /proposals/{proposal_id}/dashboard
• GET /proposals/{proposal_id}/brief
• GET /proposals/{proposal_id}/ledger

Testing

bash test.sh

That runs pytest and python3 -m build.

Notes

• Resident identity is kept pseudonymous through resident_key.
• The current codebase is backend-first and designed for mobile, SMS, and field-capture integrations.