# CivicSwarm Agent Guide

## Architecture

- `civicswarm/db.py` defines the SQLite schema and engine setup.
- `civicswarm/analysis.py` contains TF-IDF clustering, extractive summarization, language detection, and lightweight sentiment heuristics.
- `civicswarm/service.py` is the domain layer for proposals, comments, routing, privacy-preserving preference aggregation, the deliberation ledger, dashboard metrics, and civic brief export.
- `civicswarm/api.py` exposes the service through FastAPI.

## Tech Stack

- Python 3.11
- FastAPI for the HTTP surface
- SQLAlchemy Core with SQLite for persistence
- scikit-learn and numpy for topic clustering and routing similarity
- langdetect for best-effort multilingual handling

## Working Rules

- Keep resident identity pseudonymous. Use `resident_key` values only; do not add raw identity storage.
- Prefer the smallest correct change.
- Keep logic deterministic where possible so tests remain stable.
- Add or update tests for every behavior change.
- Do not remove or rewrite unrelated files.

## Testing

- Install dependencies and run the suite: `bash test.sh`
- `test.sh` must succeed with `pytest` and `python3 -m build`.

## Packaging

- Distribution name: `idea198-civicswarm-privacy-preserving`
- README must stay current because it is wired into package metadata.