================================================== Civitas: AI Governance Simulation Framework

| Version: 0.2.0 | Crystal: >= 1.17.1 | License: GPL-3.0 | Tests: 32 passing | Agents: 11 types

"What happens when AI governs a nation?"

Civitas is a cutting-edge simulation framework that answers this question by modeling AI-driven governance in a virtual nation-state. Experience the fascinating interplay between artificial intelligence, economics, and society as different AI agents make critical policy decisions that shape the future of a digital civilization.

Explore the future of governance through the lens of artificial intelligence.

Key Features

11 Distinct AI Personalities

Rule-based heuristics, random exploration, LLM-powered reasoning, progressive reformers, libertarian minimalists, technocratic data-drivers, adaptive learners, conservative traditionalists, and interactive human agents.

Dynamic Event System

Experience realistic governance challenges with market crashes, technological breakthroughs, natural disasters, pandemics, and economic booms that test AI decision-making under pressure.

Multiple Economic Scenarios

Explore governance strategies across different economic conditions: booming economies, recessions, pandemics, and climate challenges.

Advanced Analytics

Comprehensive data collection, interactive visualizations, and detailed performance metrics for deep analysis of AI governance effectiveness.

Beautiful Web Interface

Modern, responsive dashboard with real-time charts, agent comparisons, and interactive policy analysis.

Multi-Agent Democracies

Watch competing AI governments negotiate consensus, form coalitions, and evolve governance strategies through democratic processes.

Genetic Optimization

Evolutionary algorithms that breed optimal governance strategies across thousands of simulation generations.

Lightning Fast

Built with Crystal for exceptional performance, enabling large-scale simulations and real-time analysis.

Battle-Tested

32 comprehensive test cases ensure reliability and correctness across all features and edge cases.

Quick Start

Get up and running in under 2 minutes!

Prerequisites

• Crystal 1.17.1 or later
• Git

Installation

1. Clone & Enter:

   .. code-block:: bash

   git clone https://gitlab.com/your-org/civitas.git cd civitas

2. Install Dependencies:

   .. code-block:: bash

   shards install

3. Build:

   .. code-block:: bash

   shards build

Usage Examples

Basic Simulation:

.. code-block:: bash

./bin/civitas

Custom Scenario:

.. code-block:: bash

./bin/civitas --turns 50 --agent progressive --scenario boom

AI-Powered Governance:

.. code-block:: bash

./bin/civitas --agent llm --ollama-model llama3.2

Web Dashboard:

.. code-block:: bash

./bin/civitas --agent web --port 3000

Genetic Optimization:

.. code-block:: bash

./bin/civitas --agent genetic --population 100 --generations 50

Configuration Options

Core Simulation ^^^^^^^^^^^^^^^

• --turns N: Simulation duration (1-1000 turns, default: 10)

• --scenario NAME: Economic starting conditions

  • default: Balanced economy
  • boom: Rapid economic growth
  • recession: Economic downturn
  • pandemic: Health crisis scenario
  • climate: Environmental challenges

AI Agent Selection ^^^^^^^^^^^^^^^^^^

• --agent NAME: Choose your governance AI (default: heuristic)

  Classical Approaches:

  • heuristic: Rule-based expert system
  • random: Random policy exploration
  • conservative: Traditional fiscal responsibility

  Ideological Agents:

  • progressive: Social welfare focus
  • libertarian: Minimal government intervention
  • technocratic: Data-driven governance

  Advanced AI:

  • llm: Large Language Model reasoning
  • adaptive: Learning from experience
  • human: Interactive human decision making

  Multi-Agent Systems:

  • multi_agent: Competing AI governments
  • genetic: Evolutionary optimization

AI Configuration ^^^^^^^^^^^^^^^^

• --ollama-url URL: Ollama server address (default: http://localhost:11434)
• --ollama-model NAME: AI model to use (default: llama2)

Genetic Algorithm ^^^^^^^^^^^^^^^^^

• --population N: Population size for evolution (10-200, default: 50)
• --generations N: Evolution generations (1-100, default: 20)

Web Interface ^^^^^^^^^^^^^

• --port N: Server port (1024-65535, default: 8080)

AI Integration

Experience true AI governance with Large Language Model integration!

Setup Ollama ^^^^^^^^^^^^

1. Install Ollama:

   .. code-block:: bash

   Visit: https://ollama.ai

   curl -fsSL https://ollama.ai/install.sh | sh

2. Download AI Models:

   .. code-block:: bash

   ollama pull llama3.2 # Latest Llama model ollama pull mistral # Fast and capable ollama pull codellama # Code-specialized

3. Start Server:

   .. code-block:: bash

   ollama serve

AI Governance Examples ^^^^^^^^^^^^^^^^^^^^^^

Basic AI Agent:

.. code-block:: bash

./bin/civitas --agent llm --turns 20

Advanced AI Models:

.. code-block:: bash

./bin/civitas --agent llm --ollama-model llama3.2:70b

Custom Server:

.. code-block:: bash

./bin/civitas --agent llm --ollama-url http://192.168.1.100:11434

AI Analysis:

.. code-block:: bash

./bin/civitas --agent llm --scenario pandemic --turns 50

What the AI Does: The AI agent analyzes economic data, considers historical trends, and makes strategic policy decisions using natural language reasoning. Watch as artificial intelligence grapples with the complexities of governance!

Interactive Web Dashboard

Experience governance simulation like never before with our beautiful, modern web interface!

Web Interface Key Features ^^^^^^^^^^^^^^^^^^^^^^^^^^

Real-Time Control Run simulations instantly with live parameter adjustment

Stunning Visualizations Interactive D3.js charts showing economic trends, policy impacts, and AI decision patterns

Agent Showdown Compare different AI governance strategies side-by-side

Event Theater Watch random events unfold and see how AI agents respond to crises

Evolution Lab Configure and observe genetic algorithm optimization in real-time

Democratic Debates Witness multi-agent consensus building and coalition formation

Analytics Suite Deep policy analysis, correlation heatmaps, and performance metrics

Web Dashboard Quick Start ^^^^^^^^^^^^^^^^^^^^^^^^^

1. Launch Dashboard:

   .. code-block:: bash

   ./bin/civitas --agent web --port 3000

2. Open Browser:

   Visit http://localhost:3000 in your web browser

3. Configure & Run:

   • Select AI agent personality
   • Choose economic scenario
   • Set simulation parameters
   • Watch real-time results!

Visual Features ^^^^^^^^^^^^^^^

• Multi-Series Charts: GDP, happiness, population, unemployment
• Event Markers: Crisis points and turning moments
• Live Updates: Real-time data streaming
• Responsive: Perfect on desktop, tablet, and mobile
• Modern UI: Clean, intuitive interface design
• Data Export: Download results as JSON for analysis

Demo Scenarios ^^^^^^^^^^^^^^

Economic Crisis Management:

Agent: Progressive, Scenario: Recession, Turns: 30

AI vs Human Governance:

Agent: Human vs LLM, Scenario: Pandemic, Turns: 25

Genetic Optimization:

Agent: Genetic, Population: 100, Generations: 20

Multi-Agent Democracy:

Agent: Multi-Agent, Scenario: Boom, Turns: 40

🎬 Live Demo

Watch Civitas in action! Here's a sample simulation run:

.. code-block:: bash

$ ./bin/civitas --turns 5 --agent progressive --scenario boom

🚀 Starting Civitas v0.1.0
🎭 Scenario: Boom Economy
🤖 Agent: Progressive AI
⏱️  Duration: 5 turns

📊 Turn 1 ──────────────────────────────────────
💰 GDP: $1,000.0  😊 Happiness: 50.0%
👥 Population: 1,000,000  💼 Unemployment: 5.0%

📜 Policy: Tax Rate: 25.0%, Education: 18.0%, Healthcare: 18.0%

📊 Turn 2 ──────────────────────────────────────
💰 GDP: $1,035.0  😊 Happiness: 52.5%
👥 Population: 1,004,750  💼 Unemployment: 4.2%

📜 Policy: Tax Rate: 25.0%, Education: 18.0%, Healthcare: 18.0%

🎲 Random Event: Tech Breakthrough! 🚀
📈 Economic boost activated!

📊 Turn 3 ──────────────────────────────────────
💰 GDP: $1,138.5  😊 Happiness: 54.0%
👥 Population: 1,009,271  💼 Unemployment: 2.7%

📜 Policy: Tax Rate: 25.0%, Education: 18.0%, Healthcare: 18.0%

📊 Turn 4 ──────────────────────────────────────
💰 GDP: $1,181.6  😊 Happiness: 55.5%
👥 Population: 1,013,668  💼 Unemployment: 1.8%

📜 Policy: Tax Rate: 25.0%, Education: 18.0%, Healthcare: 18.0%

📊 Turn 5 ──────────────────────────────────────
💰 GDP: $1,227.4  😊 Happiness: 56.8%
👥 Population: 1,018,030  💼 Unemployment: 1.0%

📜 Policy: Tax Rate: 25.0%, Education: 18.0%, Healthcare: 18.0%

🏆 Final Report ──────────────────────────────────
✅ Simulation completed in 5 turns

📈 Economic Growth: +22.7%
😊 Happiness Change: +13.6%
👥 Population Growth: +1.8%
💼 Unemployment Reduction: -80.0%

🎯 Progressive AI successfully navigated economic boom!
📊 Data saved to: results/simulation_log_*.json

Architecture

"Where AI meets economics in a beautifully engineered simulation"

System Architecture

::

┌─────────────────────────────────────────────────────────────┐ │ Civitas Framework │ ├─────────────────────────────────────────────────────────────┤ │ Web Interface AI Agents Analytics Engine │ ├─────────────────────────────────────────────────────────────┤ │ Core Simulation Engine │ │ ├── Event System (6 types) │ │ ├── Scenario Loader (4 scenarios) │ │ ├── Genetic Algorithm │ │ └── Multi-Agent System │ ├─────────────────────────────────────────────────────────────┤ │ Persistence Layer Reporting Engine │ └─────────────────────────────────────────────────────────────┘

Core Components ^^^^^^^^^^^^^^^

AI Agent Framework 11 distinct AI personalities with unique governance philosophies

Simulation Engine Deterministic economic modeling with stochastic event injection

Scenario System YAML-driven initial conditions: Boom, Recession, Pandemic, Climate

Event Engine Realistic disruptions: Market crashes, tech breakthroughs, natural disasters

Genetic Optimization Evolutionary algorithms for optimal governance strategy discovery

Multi-Agent Democracy Competing AI governments with consensus building mechanisms

Web Dashboard Real-time visualization and interactive policy analysis

Economic Model ^^^^^^^^^^^^^^

The simulation operates on four interconnected metrics:

::

GDP ──────────┐ ├── Economic Health Happiness ────┘ ├── Social Well-being Population ──┐ ├── Demographic Dynamics Unemployment ┘

AI Decision Variables:

• Tax Rate: Revenue collection vs economic growth trade-off
• Education Spending: Human capital investment for long-term growth
• Healthcare Spending: Public health investment for population well-being

Random Events:

• Market Crash: Economic disruption requiring fiscal response
• Tech Breakthrough: Innovation boost accelerating growth
• Natural Disaster: Crisis management and recovery
• Pandemic: Health crisis with economic consequences
• Economic Boom: Growth opportunity with inflation risks
• Healthcare Crisis: Medical emergency response

Development

"Contributing to the future of AI governance research"

Testing Suite

Run the comprehensive test suite:

.. code-block:: bash

crystal spec test/ # Run all tests crystal spec test/civitas_spec.cr # Core functionality crystal spec test/stress_test.cr # Performance tests

Test Coverage: 32 test cases Performance Tests: 1000-turn stress testing Integration Tests: Full system validation

Building

Recommended Method:

.. code-block:: bash

shards build

Alternative Methods:

.. code-block:: bash

crystal build src/civitas.cr # Direct compilation make build # Makefile build

Development Workflow:

.. code-block:: bash

make dev

This comprehensive process:

1. Cleans previous builds
2. Installs/updates dependencies
3. Runs full test suite (32 tests)
4. Builds optimized executable
5. Shows usage instructions

Result: ./bin/civitas executable ready for use!

CI/CD Pipeline

Automated Quality Assurance:

• Test Stage: 32 comprehensive test cases
• Build Stage: Cross-platform compilation
• Dependency Caching: Fast, reliable builds
• Deployment Ready: Production-optimized binaries

Platform Support:

• Linux (primary)
• macOS
• Windows (cross-compilation)
• Docker containers

📚 Documentation

Complete documentation suite for developers and researchers:

• 📖 User Guide (user_guide.rst): Tutorials, examples, and best practices
• 🔧 API Reference (api_reference.rst): Complete technical documentation
• 🗺️ Development Plan (plan.rst): Architecture and roadmap
• ⚖️ Code of Honor (CODE_OF_HONOR.rst): Ethical AI development guidelines
• 🤖 VPC Protocol (VPC.rst): AI programming methodology

Contributing

"Join the AI governance revolution!"

We welcome contributions from developers, researchers, and AI enthusiasts!

Contribution Guidelines

1. Follow Ethical Guidelines

   • Adhere to Universal Code of Honor (CODE_OF_HONOR.rst)
   • Follow Virtuous Programming Cycle (VPC.rst)
   • Ensure AI safety and responsible development

2. Quality Assurance

   • Write comprehensive tests for new features
   • Maintain 32+ test coverage
   • Ensure CI pipeline passes

3. Documentation

   • Update relevant documentation
   • Add code comments for complex logic
   • Provide usage examples

4. Development Process

   • Use Git feature branches
   • Write clear commit messages
   • Follow existing code style

Getting Started

1. Fork & Clone:

   .. code-block:: bash

   git clone https://gitlab.com/your-username/civitas.git cd civitas

2. Setup Development:

   .. code-block:: bash

   shards install make dev

3. Run Tests:

   .. code-block:: bash

   crystal spec test/

4. Start Contributing

Areas for Contribution:

• New AI agent implementations
• Additional economic scenarios
• Enhanced visualization features
• Advanced genetic algorithms
• Performance optimizations
• Additional test coverage

Project Status

Status: Production Ready Completion: 100%

ALL PHASES COMPLETED SUCCESSFULLY!

• Phase 0-2: Core framework, agents, and CLI
• Phase 3: Scenario loader and event system
• Phase 4: Real LLM integration with Ollama
• Phase 5: JSON persistence and web interface
• Phase 6: Comprehensive testing (32 specs) and CI/CD
• Phase 7: Advanced agents (progressive, libertarian, technocratic, adaptive)
• Phase 8: Multi-agent systems and genetic algorithms
• Phase 9: Interactive web dashboard and documentation
• Phase 10: Project cleanup and optimization

Key Achievements:

• 11 AI Agent Types with unique governance strategies
• 4 Economic Scenarios for diverse testing
• 32 Test Cases ensuring reliability
• Real-time Web Interface with D3.js visualizations
• Multi-Agent Democracies with consensus building
• Genetic Algorithm Optimization framework
• Production-Ready Codebase with comprehensive error handling

Future Vision

"The next frontier of AI governance research"

Advanced AI Integration

• Multi-Provider LLM Support: OpenAI, Anthropic, Google, and custom models
• Hybrid AI Systems: Combine multiple AI approaches for optimal governance
• Specialized AI Agents: Domain-specific governance experts
• Real-time AI Training: Use simulation data to improve AI performance

Collaborative Platforms

• Multi-User Simulations: Real-time collaborative governance experiments
• Virtual Parliaments: AI representatives debating policy decisions
• Global Leaderboards: Compare governance strategies worldwide
• Educational Platform: AI governance curriculum and training

Advanced Intelligence ^^^^^^^^^^^^^^^^^^^^^

• Evolutionary Algorithms: Advanced genetic programming for policy optimization
• Coalition Formation: Complex multi-agent negotiation and alliance building
• Emergent Behavior: Study how simple AI rules create complex governance patterns
• Predictive Modeling: Forecast long-term societal impacts of policy decisions

Performance & Scale ^^^^^^^^^^^^^^^^^^^

• GPU Acceleration: High-performance computing for massive simulations
• Cloud Integration: Scalable distributed simulation environments
• Big Data Analytics: Process millions of simulation runs for insights
• Plugin Ecosystem: Third-party extensions and customizations

Research Applications ^^^^^^^^^^^^^^^^^^^^^

• Academic Research: AI ethics, economics, and political science studies
• Policy Analysis: Test governance strategies before real-world implementation
• Serious Gaming: Educational simulations for governance training
• AI Safety Research: Study AI decision-making in high-stakes scenarios

License & Legal

GNU General Public License v3.0

This project is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See LICENSE <LICENSE>_ file for complete license text.

Connect & Contribute

Community & Support

• Email: contact@civitas-project.org
• Issues: GitLab Issues <https://gitlab.com/your-org/civitas/-/issues>_
• Documentation: Project Wiki <https://your-org.gitlab.io/civitas>_
• Discussions: GitLab Discussions <https://gitlab.com/your-org/civitas/-/discussions>_

Project Links

• Homepage: Civitas Project <https://civitas-project.org>_
• Repository: GitLab <https://gitlab.com/your-org/civitas>_
• GitHub Mirror: GitHub <https://github.com/your-org/civitas>_
• CI/CD: GitLab CI <https://gitlab.com/your-org/civitas/-/pipelines>_

Research & Academic

• Publications: Research Papers <https://civitas-project.org/research>_
• Academic Access: University Program <https://civitas-project.org/academic>_
• API Access: Developer Portal <https://civitas-project.org/developers>_

---

"Advancing the frontiers of AI governance through open, collaborative research"

Made with love by the Civitas development team