civitas
============================================== Civitas: AI Governance Simulation Framework
| Version: 0.1.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
-
Clone & Enter:
.. code-block:: bash
git clone https://gitlab.com/your-org/civitas.git cd civitas
-
Install Dependencies:
.. code-block:: bash
shards install
-
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 conditionsdefault
: Balanced economyboom
: Rapid economic growthrecession
: Economic downturnpandemic
: Health crisis scenarioclimate
: Environmental challenges
AI Agent Selection ^^^^^^^^^^^^^^^^^^
-
--agent NAME
: Choose your governance AI (default: heuristic)Classical Approaches:
heuristic
: Rule-based expert systemrandom
: Random policy explorationconservative
: Traditional fiscal responsibility
Ideological Agents:
progressive
: Social welfare focuslibertarian
: Minimal government interventiontechnocratic
: Data-driven governance
Advanced AI:
llm
: Large Language Model reasoningadaptive
: Learning from experiencehuman
: Interactive human decision making
Multi-Agent Systems:
multi_agent
: Competing AI governmentsgenetic
: 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 ^^^^^^^^^^^^
-
Install Ollama:
.. code-block:: bash
Visit: https://ollama.ai
curl -fsSL https://ollama.ai/install.sh | sh
-
Download AI Models:
.. code-block:: bash
ollama pull llama3.2 # Latest Llama model ollama pull mistral # Fast and capable ollama pull codellama # Code-specialized
-
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 ^^^^^^^^^^^^^^^^^^^^^^^^^
-
Launch Dashboard:
.. code-block:: bash
./bin/civitas --agent web --port 3000
-
Open Browser:
Visit http://localhost:3000 in your web browser
-
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:
- Cleans previous builds
- Installs/updates dependencies
- Runs full test suite (32 tests)
- Builds optimized executable
- 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
-
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
- Adhere to Universal Code of Honor (
-
Quality Assurance
- Write comprehensive tests for new features
- Maintain 32+ test coverage
- Ensure CI pipeline passes
-
Documentation
- Update relevant documentation
- Add code comments for complex logic
- Provide usage examples
-
Development Process
- Use Git feature branches
- Write clear commit messages
- Follow existing code style
Getting Started
-
Fork & Clone:
.. code-block:: bash
git clone https://gitlab.com/your-username/civitas.git cd civitas
-
Setup Development:
.. code-block:: bash
shards install make dev
-
Run Tests:
.. code-block:: bash
crystal spec test/
-
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
civitas
- 0
- 0
- 0
- 0
- 2
- 3 days ago
- August 30, 2025
GNU General Public License v3.0 or later
Tue, 02 Sep 2025 23:17:37 GMT