Simulacrum is a comprehensive toolkit that transforms AI systems into sophisticated reality simulators. By providing advanced mathematical modeling, system dynamics simulation, and chaos analysis, it enables AI to understand and predict complex real-world phenomena through rigorous computational methods.
- System Dynamics Simulation - Model complex systems with differential equations and feedback loops
- Scenario Comparison - A/B testing for reality with sophisticated similarity metrics
- Feedback Loop Analysis - Identify reinforcing/balancing loops and their systemic impact
- Belief Dynamics - Theory of Mind simulation for social and cognitive modeling
- Game Theory Analysis - Strategic equilibrium analysis and learning dynamics
- Bayesian Reasoning - Replace "I think" with probabilistic evidence-based analysis
- Chaos Detection - Identify black swan events and early warning signals
- Conceptual Vector Analysis - Analyze complex relationships and conflicts in multi-dimensional spaces
- Monte Carlo Simulation - Stochastic modeling with uncertainty quantification and risk analysis
- Mathematical Optimization - Linear/nonlinear programming with constraint support
- Causal Graph Analysis - Counterfactual reasoning with Pearl's do-operator and d-separation
- Network Analysis - Graph theory with centrality measures and community detection
- Sensitivity Analysis - Parameter importance ranking with Sobol indices and Morris screening
- 100% Test Coverage - Comprehensive testing with pytest and hypothesis
- MCP Integration - Seamless Cursor AI integration via Model Context Protocol
- Python 3.8 or higher
- pip package manager
-
Clone the repository:
git clone https://github.com/codesmirnov/simulacrum-mcp.git cd simulacrum-mcp -
Install dependencies:
pip install -r requirements.txt
-
Install the package:
pip install -e .
-
Configure MCP in Cursor: Add to your Cursor settings (
.cursorrulesor global settings):{ "mcp": { "servers": { "simulacrum": { "command": "python", "args": ["-m", "simulacrum.server"], "env": {} } } } } -
Verify installation:
simulacrum-server --help
from simulacrum import DynamicsSimulator
# Define a predator-prey model
scenario = {
"name": "Lotka-Volterra Predator-Prey",
"variables": [
{"name": "prey", "initial_value": 10.0, "min_value": 0},
{"name": "predator", "initial_value": 5.0, "min_value": 0}
],
"equations": [
{
"target_variable": "prey",
"expression": "prey * (2.0 - 0.01 * predator)"
},
{
"target_variable": "predator",
"expression": "predator * (-1.0 + 0.01 * prey)"
}
],
"config": {
"time_config": {
"end_time": 50.0,
"time_step": 0.1
}
}
}
simulator = DynamicsSimulator()
result = simulator.simulate_dynamics(scenario)
print(f"Simulation completed: {result['status']}")from simulacrum import ProbabilityAnalyzer
analyzer = ProbabilityAnalyzer()
# Update beliefs with evidence
analysis = {
"analysis_type": "bayesian_update",
"prior": {"rain": 0.3, "no_rain": 0.7},
"likelihood": {
"cloudy": {"rain": 0.8, "no_rain": 0.4}
},
"evidence": [
{"hypothesis": "rain", "observation": "cloudy", "strength": 1.0}
]
}
result = analyzer.analyze_probability(analysis)
print(f"Updated belief in rain: {result['final_posterior']['rain']:.2%}")from simulacrum import ChaosAnalyzer
analyzer = ChaosAnalyzer()
# Analyze time series for chaotic behavior
time_series_data = {
"time_series": [0.1, 0.15, 0.08, 0.12, 0.18, 0.14, 0.09, 0.16, ...]
}
result = analyzer.analyze_chaos(time_series_data)
print(f"System state: {result['overall_assessment']['system_state']}")
print(f"Risk level: {result['overall_assessment']['risk_level']}")from simulacrum import VectorAnalyzer
analyzer = VectorAnalyzer()
# Analyze strategic alignment between different entities
vectors = [
{
"name": "Innovation_Focus",
"components": {"growth": 0.8, "stability": -0.2, "innovation": 0.9}
},
{
"name": "Market_Reality",
"components": {"growth": 0.3, "stability": 0.7, "innovation": 0.1}
}
]
strengths = [
{"name": "Innovation_Focus", "value": 1.5},
{"name": "Market_Reality", "value": 1.0}
]
result = analyzer.multidimensional_vector_analysis(vectors, strengths)
print(f"Total system magnitude: {result['total_magnitude']:.4f}")
print(f"Top dimensions: {', '.join([d['dimension'] for d in result['top_dimensions']])}")from simulacrum import MonteCarloSimulator
simulator = MonteCarloSimulator()
# Model with uncertainty
def profit_model(price, cost, demand):
return (price - cost) * demand
simulation = {
"model": profit_model,
"parameter_distributions": {
"price": {"type": "normal", "params": {"mean": 100, "std": 10}},
"cost": {"type": "uniform", "params": {"low": 60, "high": 80}},
"demand": {"type": "triangular", "params": {"low": 50, "mode": 100, "high": 200}}
},
"n_iterations": 5000,
"confidence_levels": [0.95, 0.99]
}
result = simulator.simulate_monte_carlo(simulation)
print(f"Expected profit: ${result['statistics']['output']['mean']:.0f}")
print(f"95% VaR: ${result['statistics']['output']['risk_metrics']['var_95']:.0f}")from simulacrum import CausalAnalyzer
analyzer = CausalAnalyzer()
# Define causal graph
causal_graph = {
"nodes": ["Smoking", "Cancer", "Age"],
"edges": [("Smoking", "Cancer"), ("Age", "Cancer"), ("Age", "Smoking")],
"queries": [{
"type": "causal_effect",
"cause": "Smoking",
"effect": "Cancer"
}]
}
result = analyzer.analyze_causal_graph(causal_graph)
effect = result["queries"][0]
print(f"Causal effect identifiable: {effect['identifiable']}")Run the comprehensive test suite:
# Install test dependencies
pip install -e ".[dev]"
# Run all tests with coverage
pytest --cov=simulacrum --cov-report=html
# Run specific test categories
pytest tests/test_dynamics.py
pytest tests/test_probability.py
pytest tests/test_chaos.py
pytest tests/test_vector_analysis.py- Single Responsibility - Each class has one clear purpose
- Open/Closed - Extensible without modifying existing code
- Liskov Substitution - Subtypes are substitutable for base types
- Interface Segregation - Clients depend only on methods they use
- Dependency Inversion - Depend on abstractions, not concretions
simulacrum/
├── core/ # Core engine and interfaces
├── tools/ # Analysis tools and simulators
├── validation/ # Data validation and type safety
└── server.py # MCP server implementation
We welcome contributions! Please see our Contributing Guide for details.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
For security-related issues, please see our Security Policy.
# Clone and setup
git clone https://github.com/codesmirnov/simulacrum-mcp.git
cd simulacrum-mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
black simulacrum/
isort simulacrum/
mypy simulacrum/This project is licensed under the MIT License - see the LICENSE file for details.
- Built for the AI safety and alignment research community
- Inspired by system dynamics, chaos theory, and Bayesian epistemology
- Designed for practical deployment in AI assistant systems
codesmirnov
- GitHub: @codesmirnov
- Email: hello@codesmirnov.ru
Transforming AI from pattern recognition to reality simulation.