# 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

```bash
python3 -m pip install -e .
```

For development:

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

## Run

```bash
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
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.