Large-scale AI-powered analysis of urban AI risks in news media.
UAIR (Urban AI Risks) is a scalable pipeline framework for assessing AI-related risks in urban contexts through large-scale inference over news article datasets. The framework enables researchers to:
- Classify articles for AI relevance using LLM-powered or heuristic methods
- Categorize articles into risk taxonomies (climate adaptation, governance, ethics)
- Extract structured information about AI deployments and impacts
- Cluster articles by topic to discover emerging patterns
- Verify claims and validate extracted information
- Configuration-Driven: Define complex multi-stage dagspaces in YAML, no code changes needed
- Scalable: Process millions of articles using Ray Data and SLURM clusters
- LLM-Integrated: Built-in vLLM support with automatic GPU management
- Modular: Mix and match stages, models, and datasets
- Tracked: Automatic experiment logging with Weights & Biases
- Extensible: Easy to add custom processing stages
# Clone the repository
git clone https://github.com/your-org/UAIR.git
cd UAIR
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install dependencies
uv pip install -r requirements.txt# Topic modeling on a sample of articles
python -m dagspaces.uair.cli \
runtime.debug=true \
runtime.sample_n=100 \
data.parquet_path=/path/to/articles.parquet# Complete pipeline: classify → taxonomy → verify
python -m dagspaces.uair.cli \
pipeline=taxonomy_full \
data.parquet_path=/path/to/articles.parquetResults are saved to outputs/ with full experiment tracking in W&B.
Complete documentation is available in docs/:
- Documentation Hub - Documentation navigation and index
- User Guide - Complete introduction with Quick Start
- Quick Reference - Command cheat sheet
- Configuration Guide - Pipeline recipes and config patterns
- Custom Stages Guide - Building custom processing stages
| Level | Time | What to Read |
|---|---|---|
| Beginner | 1-2 hours | User Guide (Intro + Quick Start + Core Concepts) |
| Intermediate | 3-4 hours | Configuration Guide (Pipeline Recipes) |
| Advanced | 5+ hours | Custom Stages Guide (Build custom stages) |
┌─────────────────────────────────────────────────────────────────┐
│ Pipeline Definition (YAML) │
├─────────────────────────────────────────────────────────────────┤
│ Sources → Stage 1 → Stage 2 → Stage 3 → Outputs │
│ (Data) (classify) (taxonomy) (verify) (Parquet) │
├─────────────────────────────────────────────────────────────────┤
│ Orchestrator (DAG Execution Engine) │
├─────────────────────────────────────────────────────────────────┤
│ Ray Data (Distributed) | vLLM (GPU) | SLURM (Cluster) | W&B │
├─────────────────────────────────────────────────────────────────┤
│ Hydra (Configuration Management) │
└─────────────────────────────────────────────────────────────────┘
| Stage | Purpose | Input | Output |
|---|---|---|---|
| classify | Relevance filtering | Raw articles | is_relevant flag |
| taxonomy | Risk categorization | Articles | chunk_label (risk category) |
| decompose | Info extraction | Articles | Structured fields |
| topic | Topic modeling | Articles | topic_id, cluster info |
| verification | Claim validation | Labeled articles | Verification scores |
UAIR/
├── docs/ # Documentation
│ ├── README.md # Documentation hub
│ ├── USER_GUIDE.md # Complete user guide
│ ├── CUSTOM_STAGES_GUIDE.md # Build custom stages
│ ├── CONFIGURATION_GUIDE.md # Config recipes
│ └── QUICK_REFERENCE.md # Cheat sheet
├── dagspaces/uair/ # Core framework
│ ├── cli.py # CLI entry point
│ ├── orchestrator.py # Pipeline orchestrator
│ ├── config_schema.py # Configuration schemas
│ ├── wandb_logger.py # W&B integration
│ ├── conf/ # Configuration files
│ │ ├── config.yaml # Base config
│ │ ├── data/ # Data source configs
│ │ ├── model/ # Model configs
│ │ ├── prompt/ # Prompt templates
│ │ ├── pipeline/ # Pipeline definitions
│ │ └── hydra/launcher/ # SLURM configs
│ └── stages/ # Processing stages
│ ├── classify.py # Relevance classification
│ ├── taxonomy.py # Risk categorization
│ ├── topic.py # Topic modeling
│ ├── verify.py # Verification
│ └── decompose.py # Information extraction
├── scripts/ # Utility scripts
├── data/ # Data directory
├── outputs/ # Pipeline outputs
└── requirements.txt # Python dependencies
Analyze news coverage of AI deployments in urban contexts:
# conf/pipeline/urban_risks.yaml
pipeline:
graph:
nodes:
classify: # Filter AI-relevant articles
stage: classify
taxonomy: # Categorize by risk type
stage: taxonomy
depends_on: [classify]
verify: # Validate claims
stage: verification
depends_on: [taxonomy]Adapt for other domains (medical, legal, scientific):
- Define your taxonomy in
conf/taxonomy/my_domain.yaml - Create custom prompts in
conf/prompt/my_prompts.yaml - Build pipeline in
conf/pipeline/my_pipeline.yaml - Run:
python -m dagspaces.uair.cli pipeline=my_pipeline
See Custom Stages Guide for details.
# Discover topics in your dataset
python -m dagspaces.uair.cli \
pipeline=cluster_topic \
topic.embed.device=cuda \
data.parquet_path=/data/articles.parquet# Full pipeline with classification, taxonomy, and verification
python -m dagspaces.uair.cli \
pipeline=taxonomy_full \
runtime.sample_n=1000 \
data.parquet_path=/data/articles.parquet# Override GPU and batch settings
python -m dagspaces.uair.cli \
pipeline=my_pipeline \
model.engine_kwargs.max_model_len=8192 \
model.batch_size=16 \
model.engine_kwargs.tensor_parallel_size=4More examples in Configuration Guide.
# Run locally (no SLURM)
python -m dagspaces.uair.cli \
hydra/launcher=null \
runtime.sample_n=100# Submit to SLURM with GPU
python -m dagspaces.uair.cli \
pipeline=my_pipeline \
hydra/launcher=slurm_gpu_4xSee Configuration Guide - SLURM Launchers for details.
UAIR uses Hydra for hierarchical configuration:
# config.yaml
defaults:
- data: inputs
- model: vllm_qwen3-30b
- prompt: classify
- pipeline: null
runtime:
debug: false
sample_n: null
output_root: ./outputs
pipeline:
sources:
articles:
path: ${data.parquet_path}
graph:
nodes:
# Define your stages hereOverride from command line:
python -m dagspaces.uair.cli \
runtime.debug=true \
model.batch_size=8 \
data.parquet_path=/path/to/data.parquetSee Configuration Guide for comprehensive patterns.
# Install dev dependencies
pip install -r requirements-dev.txt
# Run tests
pytest tests/
# Run with coverage
pytest --cov=dagspaces tests/- Implement stage function in
dagspaces/uair/stages/mystage.py:
def run_mystage(df, cfg):
# Your processing logic
return df- Register stage in
orchestrator.py:
class MyStageRunner(StageRunner):
stage_name = "mystage"
def run(self, context):
# ...- Add to registry:
_STAGE_REGISTRY["mystage"] = MyStageRunner()Full guide: Custom Stages Guide
This framework supports the Urban AI Risks research project, assessing AI deployment risks in urban contexts through large-scale news analysis.
Related Work:
- Climate adaptation taxonomy (Weitz et al.)
- AI risk frameworks
- Urban AI governance
We welcome contributions! Areas of interest:
- New Stages: Additional processing capabilities
- Taxonomies: Domain-specific risk categorizations
- Optimizations: Performance improvements
- Documentation: Examples, tutorials, guides
See Custom Stages Guide for implementation guidelines.
MIT License - see LICENSE file for details.
- Start with User Guide
- Check Quick Reference for common issues
- Browse Configuration Guide for recipes
GPU Out of Memory:
python -m dagspaces.uair.cli \
model.engine_kwargs.gpu_memory_utilization=0.6 \
model.batch_size=2Ray Object Store Full:
python -m dagspaces.uair.cli \
runtime.rows_per_block=1000Debug Mode:
python -m dagspaces.uair.cli \
runtime.debug=true \
runtime.sample_n=10More troubleshooting: Quick Reference - Troubleshooting
Built with:
- Hydra - Configuration management
- Ray Data - Distributed processing
- vLLM - LLM inference
- Weights & Biases - Experiment tracking
- SLURM - Cluster scheduling
For questions about the framework:
- Check the documentation
- Review examples
- Consult troubleshooting guide
For additional information, consult the User Guide - Quick Start.
Project maintained by the Urban AI Risks research team.