Content
# Social System Modeling Multi-Agent Framework
## Introduction
A lightweight multi-agent collaboration framework for deriving complete social system models from basic assumptions. Through the collaborative analysis of 7 professional Agents (Systems/Econ/Socio/Governance/Culture/Risk/Validation), a structured and verifiable social system model is generated.
**Key Features**:
- 🔬 **7 Professional Agents**: Covering systems thinking, economics, sociology, governance, culture, risk analysis, and validation
- 🔄 **6-Step Workflow**: Hypothesis validation → Parallel reasoning → Conflict alignment → Decision synthesis → Evidence validation → Iterative convergence
- ⚡ **Lightweight Implementation**: TypeScript + Bun, can be directly called by Claude/AI
- 🛠️ **MCP Protocol Support**: Standard Model Context Protocol, seamlessly integrated with Claude Desktop
- 📊 **Structured Output**: 9-layer architecture model (Overall structure/Workflow/Institutions/Governance/Culture/Innovation/Risk/Metrics/Optimization)
## Quick Start
### Installation
```bash
# Clone the project
git clone <repository-url>
cd SocialGuessSkills
# Install dependencies
bun install
# Install Biome
bun add -d biome
```
### Configure Biome
1. Initialize Biome configuration:
```bash
biome init
```
2. Edit the generated `biome.json` file to suit project needs:
```json
{
"$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
"formatter": {
"enabled": true,
"indentStyle": "space",
"lineWidth": 100
},
"linter": {
"enabled": true,
"rules": {
"recommended": true,
"correctness": {},
"style": {}
}
},
"javascript": {
"formatter": {
"quoteStyle": "single"
}
}
}
```
3. Run Biome check:
```bash
biome check
```
### Run Example
```bash
# Run end-to-end example (community governance model)
bun run examples/run-example.ts
```
**Expected Output**:
- Iterations: 2
- Confidence: 0.79
- Agent Output Count: 7 (each Agent generates analysis)
- Conflict Count: 7 (logical contradictions, priority conflicts, risk superposition)
### Run Configuration (Environment Variables)
By default, simulated output is used. You can switch between real LLM and failure strategies via environment variables:
- `LLM_PROVIDER`: `auto` | `anthropic` | `mock` (default `auto`)
- `ANTHROPIC_API_KEY`: Required when using Anthropic
- `LLM_MODEL`: Model name (default `claude-3-5-sonnet-20241022`)
- `LLM_MAX_TOKENS`: Maximum output tokens (default `4096`)
- `LLM_TIMEOUT_MS`: LLM timeout in milliseconds (default `60000`)
- `AGENT_MOCK_MODE`: Force mock (`true`/`false`, default `false`)
- `FAIL_ON_CRITICAL`: Interrupt the process when a critical Agent fails (default `true`)
- `CRITICAL_AGENTS`: List of critical Agents (default `risk,governance,systems`)
### MCP Integration (Recommended)
**Configure in Claude Desktop**:
1. Edit `claude_desktop_config.json`:
```json
{
"mcpServers": {
"social-modeling": {
"command": "bun",
"args": ["run", "/absolute/path/to/src/server.ts"]
}
}
}
```
2. Restart Claude Desktop
3. Use in Claude:
```
Please help me analyze: A community of 1000 people with limited resources. How can I establish a stable and cooperative social system?
```
Claude will automatically call the MCP Server to generate a complete social system model.
**📖 Detailed Integration Guide**: See [docs/MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md) for:
- Complete Claude Desktop configuration steps
- OpenCode CLI integration status
- Troubleshooting guide
- More usage examples and Prompt templates
## Usage Examples
### 1. Complete Reasoning (reasoning tool)
**Input**:
```json
{
"hypothesis": {
"assumptions": [
"Community of 1000 people, limited resources (food, housing, tools)",
"Collaboration can increase total output by 30%",
"No external intervention, isolated environment"
],
"constraints": [
"Communication cost: Face-to-face communication is free, indirect communication has attenuation",
"Incomplete information: Individuals only know the status of the nearest 50 people"
],
"goals": [
"Ensure basic survival for everyone (food, shelter)",
"Establish a sustainable resource production and distribution mechanism",
"Enforceable conflict resolution mechanism"
]
},
"maxIterations": 3
}
```
**Output**: Complete social system model, including:
- Analysis from 7 Agents (conclusion/basis/risk/recommendation/falsifiable points)
- Detected conflicts (type/description/severity/solution)
- 9-layer structured model (Overall structure/Workflow/Institutions/Governance/Culture/Innovation/Risk/Metrics/Optimization)
- Metadata (number of iterations/confidence/generation time)
### 2. Single Agent Query (query_agent tool)
**Input**:
```json
{
"agentType": "risk",
"hypothesis": {
"assumptions": ["Resource scarcity", "Limited rationality"],
"constraints": [],
"goals": ["Stable order"]
}
}
```
**Output**: Professional analysis from the Risk Agent, focusing on vulnerability, extreme scenarios, and resilience strategies.
### 3. Model Validation (validate_model tool)
**Input**:
```json
{
"modelJson": "{...complete model JSON string...}"
}
```
**Output**: Validation results, including:
- isValid: Whether validation passed
- checks: Detailed checks (hasAllAgents, hasStructure, hasHypothesis, etc.)
- issues: List of discovered issues
- warnings: Warning messages (e.g., too many conflicts, low confidence)
## Architecture Overview
```
┌─────────────────────────────────────────────────────┐
│ User Input Hypothesis │
│ (assumptions/constraints/goals) │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 1. Hypothesis Validation (Systems Agent) │
│ - Check structural integrity, identify key variables │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 2. Parallel Agent Reasoning (7 Agents) │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌───────┐ │
│ │Systems │ │ Econ │ │ Socio │ │Govern │ │
│ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │
│ └────────┘ └────────┘ └────────┘ └───────┘ │
│ ┌────────┐ ┌────────┐ │
│ │Culture │ │ Risk │ │
│ │ Agent │ │ Agent │ │
│ └────────┘ └────────┘ │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 3. Conflict Alignment (Risk Agent-led) │
│ - Detect logical contradictions, priority conflicts, risk superposition │
│ - Mark Agents that need to be re-reasoned │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 4. Decision Synthesis (Governance Agent-led) │
│ - Apply decision synthesis rules: hierarchical weighting, conflict priority │
│ - Extract 9-layer structured model │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 5. Evidence Validation (Validation Agent) │
│ - Falsifiable hypothesis testing, historical case comparison, counterfactual reasoning │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 6. Iterative Convergence (Return to Step 2 if Conflicts Exist) │
│ - Maximum Iterations: 3 (configurable) │
│ - Termination Condition: No New Conflicts OR Maximum Iterations Reached │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Final Social System Model │
│ - Agent Outputs (7) │
│ - Conflict List │
│ - 9-Layer Structured Model │
│ - Metadata (Iterations/Confidence/Time) │
└─────────────────────────────────────────────────────┘
```
## API Reference
### Tool 1: reasoning
Complete reasoning process, from hypothesis to complete model.
**Input**:
```json
{
"hypothesis": {
"assumptions": ["Assumption 1", "Assumption 2"],
"constraints": ["Constraint 1", "Constraint 2"],
"goals": ["Goal 1", "Goal 2"]
},
"maxIterations": 3
}
```
**Output**:
```json
{
"hypothesis": {...},
"agentOutputs": [...],
"conflicts": [...],
"structure": {
"overall": {...},
"workflow": {...},
"institutions": {...},
"governance": {...},
"culture": {...},
"innovation": {...},
"risks": {...},
"metrics": {...},
"optimization": {...}
},
"metadata": {
"iterations": 2,
"confidence": 0.79,
"generatedAt": "2026-02-03T14:30:00Z"
}
}
```
### Tool 2: query_agent
Query the analysis of a specific Agent.
**Input**:
```json
{
"agentType": "systems|econ|socio|governance|culture|risk|validation",
"hypothesis": {...}
}
```
**Output**: Complete analysis of a single Agent (conclusion/basis/risk/recommendation/falsifiable points)
### Tool 3: validate_model
Validate the consistency of an existing model.
**Input**:
```json
{
"modelJson": "{...model JSON string...}"
}
```
**Output**:
```json
{
"isValid": true,
"checks": {
"hasAllAgents": true,
"hasStructure": true,
"hasHypothesis": true,
"hasMetadata": true,
"agentTypesAreValid": true
},
"issues": [],
"warnings": []
}
```
## Extension Guide
### Customize Agent Prompt
1. Edit `src/agents/prompts/{agent}-agent.md`
2. Follow the unified format:
- `## Role Definition`
- `## Core Responsibilities`
- `## Analysis Framework`
- `## Output Format` (CRITICAL)
- `## Key Constraints`
3. No restart required after modification, AI will automatically load the latest Prompt
### Add a New Agent Type
1. Add a new AgentType in `src/types.ts`
2. Create `src/agents/prompts/{new-agent}-agent.md`
3. Register in `createAllAgents()` in `src/agents/agent-factory.ts`
4. Add corresponding test cases
### Customize Conflict Detection Rules
Add a new detection function in `src/workflow/conflict-resolver.ts`:
```typescript
function detectCustomConflict(outputs: AgentOutput[]): Conflict[] {
const conflicts: Conflict[] = [];
// Your detection logic
return conflicts;
}
```
Then call the new function in `detectConflicts()`.
## Project Structure
```
SocialGuessSkills/
├── src/
│ ├── agents/
│ │ ├── prompts/ # Prompt templates for 7 Agents
│ │ ├── agent-factory.ts # Agent factory
│ │ └── agent-executor.ts # Agent executor
│ ├── workflow/
│ │ ├── orchestrator.ts # Workflow orchestrator
│ │ └── conflict-resolver.ts # Conflict detection
│ ├── types.ts # Core type definitions
│ ├── server.ts # MCP Server entry point
│ └── __tests__/ # Test cases
├── examples/
│ ├── community-governance.json # Example input
│ └── run-example.ts # Example execution script
├── package.json
├── tsconfig.json
└── README.md
```
## Testing
Run all tests:
```bash
bun test
```
Test coverage:
- Agent Prompt file integrity
- Agent factory and execution
- Conflict detection (3 types of rules)
- Workflow orchestrator (6-step process)
- End-to-end example
- Execution time benchmark (<60 seconds)
## Contribution
Contributions are welcome! Please follow:
1. Fork the project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'feat: Add AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Create a Pull Request
**Commit Specifications**:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation update
- `refactor:` Code refactoring
- `test:` Test related
## License
MIT
## Contact Information
- Issue Feedback: GitHub Issues
- Discussion and Communication: GitHub Discussions
