idea198-civicswarm-privacy-preserving/AGENTS.md

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.