Skip to main content

Citizen Ingestion Agent

The Citizen Ingestion Agent processes citizen-reported incidents and integrates them into the platform.

πŸ“‹ Overview​

PropertyValue
Modulesrc.agents.ingestion.citizen_ingestion_agent
ClassCitizenIngestionAgent
AuthorUIP Team
Version1.0.0

🎯 Purpose​

  • Ingest citizen reports from mobile apps and web portals
  • Validate and geocode report locations
  • Classify incident types automatically
  • Correlate with sensor data for verification

πŸ“Š Report Types​

TypeDescriptionPriority
accidentTraffic accidentHigh
congestionTraffic jamMedium
hazardRoad hazardHigh
roadworkConstructionLow
floodingWater on roadHigh
otherMiscellaneousLow

πŸš€ Usage​

Ingest Report​

from src.agents.ingestion.citizen_ingestion_agent import CitizenIngestionAgent

agent = CitizenIngestionAgent()

# Ingest citizen report
report = await agent.ingest({
    "reporter_id": "USER_12345",
    "type": "accident",
    "description": "Two-car collision at intersection",
    "location": {
        "lat": 10.8231,
        "lon": 106.6297,
        "address": "Nguyen Hue Street"
    },
    "photos": ["base64_image_data"],
    "timestamp": "2025-11-29T10:30:00Z"
})

Validate Report​

# Validate against sensor data
validation = await agent.validate(report["id"])
# {
#     "valid": True,
#     "confidence": 0.85,
#     "correlated_cameras": ["CAM_001", "CAM_002"],
#     "sensor_confirmation": True
# }

Get Report Status​

# Track report processing status
status = await agent.get_status(report["id"])
# {
#     "id": "RPT_001",
#     "status": "verified",
#     "processing_time_ms": 1234,
#     "actions_taken": ["alert_dispatched", "camera_analyzed"]
# }

βš™οΈ Configuration​

# config/citizen_ingestion.yaml
citizen_ingestion:
  enabled: true
  
  # Validation settings
  validation:
    require_location: true
    require_photo: false
    max_age_minutes: 60
    geocoding:
      enabled: true
      provider: "nominatim"
  
  # Classification
  classification:
    model: "text-classification-v1"
    confidence_threshold: 0.7
  
  # Correlation
  correlation:
    camera_radius_km: 1.0
    sensor_timeout_seconds: 30
  
  # Rate limiting (per user)
  rate_limit:
    max_reports_per_hour: 10
    cooldown_seconds: 60

πŸ”„ Processing Pipeline​

graph LR
    A[Citizen Report] --> B[Validation]
    B --> C[Geocoding]
    C --> D[Classification]
    D --> E[Correlation]
    E --> F[Publish to Stellio]
    F --> G[Trigger Alerts]

πŸ“– Related Documentation​

See the complete agents reference for all available agents.