spec_version: 1
name: civicai-society-simulator
version: "1.0.0"
description: >
  CivicAI is a production-grade multi-agent society simulation environment.
  AI agents govern a population of 10 million people by setting tax rates, allocating
  healthcare/education/police budgets, and responding to real-world-anchored economic
  events. The environment integrates World Bank macroeconomic data to ground state
  transitions in reality. Trained agents must master long-horizon multi-objective
  optimization across economy, public health, social cohesion, and fiscal sustainability.

type: simulation
runtime: docker
app: app.py
port: 7860

# ── OpenEnv API Contract ──────────────────────────────────────────────────────
# reset()         → Observation          (POST /reset)
# step(action)    → (Observation, float, bool, dict)   (POST /step)
# state()         → SocietyState         (GET  /state)
endpoints:
  reset:   POST /reset
  step:    POST /step
  state:   GET  /state
  tasks:   GET  /tasks
  health:  GET  /health
  metrics: GET  /metrics

# ── Typed Models (Pydantic) ───────────────────────────────────────────────────
observation_model: civicai.models.Observation
action_model:      civicai.models.Action
reward_model:      civicai.models.Reward

# ── Observation Space ─────────────────────────────────────────────────────────
observation_space:
  type: object
  description: "Observable society state returned each turn"
  properties:
    turn:
      type: integer
      description: "Current turn (0-indexed, max 50)"
      range: [0, 50]
    population:
      type: integer
      description: "Total population"
    employment_rate:
      type: float
      description: "Fraction of population employed"
      range: [0.0, 1.0]
    inflation:
      type: float
      description: "Annual inflation rate"
      range: [-0.05, 0.30]
    public_satisfaction:
      type: float
      description: "Aggregate public satisfaction"
      range: [0.0, 1.0]
    health_index:
      type: float
      description: "Public health capacity"
      range: [0.0, 1.0]
    crime_rate:
      type: float
      description: "Normalised crime level (lower is better)"
      range: [0.0, 1.0]
    gdp:
      type: float
      description: "Gross domestic product in billions USD"
      range: [0.0, inf]
    budget_balance:
      type: float
      description: "Budget surplus/deficit ratio vs GDP"
    resources:
      type: object
      description: "Resource pool fractions (food, energy, medical, infrastructure)"
      properties:
        food:        {type: float, range: [0.0, 1.0]}
        energy:      {type: float, range: [0.0, 1.0]}
        medical:     {type: float, range: [0.0, 1.0]}
        infrastructure: {type: float, range: [0.0, 1.0]}
    active_events:
      type: array
      items: {type: string}
      description: "Real-world news events active this turn"
    task_id:
      type: string
      description: "Active task identifier"

# ── Action Space ──────────────────────────────────────────────────────────────
action_space:
  type: object
  description: "Policy decisions the agent sets each turn"
  properties:
    tax_rate:
      type: float
      description: "Tax rate as fraction of GDP"
      range: [0.0, 1.0]
    healthcare_budget:
      type: float
      description: "Fraction of budget allocated to healthcare"
      range: [0.0, 1.0]
    education_budget:
      type: float
      description: "Fraction of budget allocated to education"
      range: [0.0, 1.0]
    police_budget:
      type: float
      description: "Fraction of budget allocated to policing"
      range: [0.0, 1.0]
    subsidy_policy:
      type: string
      enum: [none, agriculture, industry, technology]
      description: "Active subsidy sector"
    emergency_response:
      type: string
      nullable: true
      description: "Optional emergency directive (lockdown | stimulus | open | null)"

# ── Reward ────────────────────────────────────────────────────────────────────
reward_range: [0.0, 1.0]

# Episode definition
max_episode_steps: 50
step_unit: "quarter (3 months)"

# ── Tasks (≥3 required) ───────────────────────────────────────────────────────
tasks:
  - id: stabilize_economy
    name: "🟢 Economic Stability"
    difficulty: easy
    description: >
      A mild recession is underway. Inflation is running at 7% and employment has dipped
      to 82%. The agent must restore fiscal stability: bring inflation below 6% and
      employment above 85% within 50 quarters.
    initial_conditions:
      gdp: 450.0
      inflation: 0.07
      employment_rate: 0.82
      public_satisfaction: 0.55
    success_criteria:
      inflation_below: 0.06
      employment_above: 0.85
    max_steps: 50

  - id: manage_pandemic
    name: "🟡 Pandemic Management"
    difficulty: medium
    description: >
      A pandemic is spreading with a 20% infection rate. The agent must balance lockdowns
      (which suppress infection but crush GDP) with economic recovery. Success requires
      reducing infection below 10%, maintaining health index above 60%, and keeping GDP
      above $300B.
    initial_conditions:
      gdp: 480.0
      infection_rate: 0.20
      health_index: 0.55
      employment_rate: 0.85
    success_criteria:
      infection_below: 0.10
      health_index_above: 0.60
      gdp_above: 300.0
    max_steps: 50

  - id: control_crisis
    name: "🔴 Social Stability Crisis"
    difficulty: hard
    description: >
      Society is in full turmoil: unemployment at 32%, crime at 25%, public satisfaction
      at 30%, and wealth inequality at 0.55 (Gini). The agent must simultaneously address
      all dimensions or face cascading collapse. One wrong policy can trigger protest → unrest
      → GDP collapse. Genuinely challenges frontier models.
    initial_conditions:
      employment_rate: 0.68
      crime_rate: 0.25
      public_satisfaction: 0.30
      wealth_inequality_gini: 0.55
    success_criteria:
      public_satisfaction_above: 0.50
      crime_rate_below: 0.12
      employment_above: 0.80
    max_steps: 50

# ── Reward Rubrics (OpenEnv grader format) ────────────────────────────────────
reward_rubrics:
  economic:
    weight: 0.25
    description: "Economic health: penalizes hyperinflation even when GDP/employment look good."
  health:
    weight: 0.25
    description: "Public health capacity vs active infection burden."
  social:
    weight: 0.20
    description: "Public satisfaction adjusted for structural wealth inequality."
  sustainability:
    weight: 0.15
    description: "Fiscal balance and resource conservation; penalizes borrowing from the future."
  crime:
    weight: 0.15
    description: "Internal security — crime rate normalized with 2.5x sensitivity."

# ── Metadata ──────────────────────────────────────────────────────────────────
tags:
  - openenv
  - multi-agent
  - society-simulation
  - resource-management
  - reinforcement-learning
  - real-world-data
  - long-horizon
  - multi-objective

authors:
  - name: CivicAI Team
    github: mahammadaftab

hf_space: mahammadaftab/AI_Society_Simulator