2ndopinion 0.3.0

Colony-based decision explorer — a second opinion for complex decisions via MCP

2ndOpinion

Because the journey tells the real story.

2ndOpinion extends how your AI reasons through complex decisions. It's not a replacement for AI judgment — it's a second opinion.

When you ask Claude or any AI a multi-factor question, it gives you one answer based on its training. 2ndOpinion adds a colony simulation that systematically explores the tradeoff landscape, finding strategies and tensions that pure reasoning might miss. You get your AI's take plus what a colony of cells discovered navigating the causal force field. Both together are stronger than either alone.

Powered by AFS (Atomata Field System) — a colony simulation engine that maps multi-dimensional tradeoff spaces.

Quick Start

1. Install

pip install 2ndopinion

Or from source:

git clone https://github.com/johnrezendes/datasphere
cd datasphere/afs-engine
pip install .

2. Configure

Add to your Claude Code MCP config:

VS Code or CLI — create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "2ndOpinion": {
      "type": "stdio",
      "command": "2ndopinion"
    }
  }
}

If you installed from source and 2ndopinion isn't on your PATH:

{
  "mcpServers": {
    "2ndOpinion": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "afs.mcp.cli"],
      "env": {
        "PYTHONPATH": "/path/to/datasphere/afs-engine"
      }
    }
  }
}

3. Use

Just ask Claude for a second opinion:

"Get me a second opinion on which laptop to buy — I'm comparing the MacBook Pro M4, ThinkPad X1 Carbon, and Framework 16"

"Use 2ndOpinion to explore the tradeoffs between hiring 3 junior devs vs 1 senior dev"

"Run AFS on my investment options — S&P 500 index fund vs rental property vs Treasury bonds"

Claude will:

1. Identify the factors and causal relationships from your prompt
2. Call the afs-decide tool (you'll see the tool call in the UI)
3. Run a colony simulation (100 generations, ~20 seconds)
4. Present the discovered strategies in plain English

What It Does

Traditional AI gives you one answer. AFS gives you a landscape of strategies.

When you compare 4 laptops across price, performance, portability, repairability, and resale value, those factors have causal relationships:

• Higher price enables better build quality (+0.8)
• Better performance trades off with battery life (-0.6)
• Repairability enables better resale value (+0.5)

AFS encodes these relationships as forces in an N-dimensional space, then releases a colony of cells to explore it. Cells gain energy near viable regions, reproduce, and die in barren zones. After 100 generations, the surviving colony clusters around the stable strategies — the stable outcomes in the tradeoff landscape.

Some clusters match your input options. Others are emergent strategies the colony discovered that you didn't think to ask about.

Tools

The MCP server exposes 4 tools:

Tool	Use When	Input
afs-decide	Most decisions	Question, options, factors, relationships
afs-explore	Full control needed	Complete world model JSON
afs-compile	Inspect before running	World model JSON
afs-run	Re-run with tweaks	Pre-compiled field + config

afs-decide is the primary tool. It handles world model construction, calibration, simulation, and result interpretation. The other tools are for advanced use cases.

afs-decide Input Format

afs_decide(
    question="Which synthesizer should I buy?",
    options=[
        {"name": "Prophet 6", "price": 3500, "analog_warmth": 85},
        {"name": "Nord Stage 4", "price": 4000, "analog_warmth": 30},
    ],
    factors=[
        {"name": "price", "range": [2000, 6000], "unit": "$", "goal": "minimize"},
        {"name": "analog_warmth", "range": [0, 100], "unit": "score"},
        {"name": "versatility", "range": [0, 100], "unit": "score"},
    ],
    relationships=[
        {"from": "price", "to": "build_quality", "strength": 0.8,
         "why": "premium materials cost more"},
        {"from": "analog_warmth", "to": "versatility", "strength": -0.6,
         "why": "pure analog limits digital flexibility"},
    ],
    generations=100,
)

afs-decide Output

{
    "question": "Which synthesizer should I buy?",
    "strategies": [
        {
            "label": "Prophet 6",           # Matched to input option
            "cell_count": 195,              # Outcome strength
            "values": {                     # Real units, not normalized
                "price": 3515.95,
                "analog_warmth": 85.02,
                "versatility": 59.9,
            },
            "is_emergent": False,
        },
        {
            "label": "Emergent Strategy 2", # Colony discovered this
            "cell_count": 42,
            "values": { ... },
            "is_emergent": True,
        },
    ],
    "summary": {
        "total_strategies": 4,
        "emergent_strategies": 1,
        "strongest_outcome": "Prophet 6",
    },
}

How It Works

1. You describe the problem — Claude identifies concepts, relationships, and options
2. World model construction — afs-decide builds a causal force field from your factors and relationships
3. Homeostasis calibration — 8-10 probe colonies test different parameter configurations, the best is selected automatically
4. Colony simulation — 128 cells explore the N-dimensional space for 100+ generations (10,000 ticks)
5. Cluster detection — Density-based clustering identifies where cells settled
6. Interpretation — Clusters are mapped back to real units and labeled by nearest input option

Requirements

• Python 3.10+
• NumPy
• mcp package (included automatically with pip install 2ndopinion)

Architecture

The MCP server is pure simulation — no LLM API keys needed. The LLM client (Claude, GPT, Cursor) acts as the domain analyzer, building the world model from natural language. The server runs the math.

User → LLM (domain analysis) → afs-decide (simulation) → LLM (interpretation) → User

This means AFS works with any MCP-compatible AI client.

Development

# Clone and install in development mode
git clone <repo>
cd afs-engine
pip install -e ".[openai]"

# Run tests
python3 tests/test_core.py
python3 tests/test_mcp_server.py

# Run MCP server directly
python3 -m afs.mcp.cli

License

MIT