Metadata-Version: 2.4
Name: 2ndopinion
Version: 0.1.0
Summary: Colony-based decision explorer — a second opinion for complex decisions via MCP
Author-email: John Rezendes <john@rezend.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/johnrezendes/datasphere/tree/main/afs-engine
Project-URL: Repository, https://github.com/johnrezendes/datasphere
Project-URL: Issues, https://github.com/johnrezendes/datasphere/issues
Keywords: decision-making,simulation,mcp,colony,tradeoffs,second-opinion
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: mcp>=1.0
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=13.0; extra == "gpu"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: all
Requires-Dist: 2ndopinion[gpu,openai]; extra == "all"
Dynamic: license-file

# 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

```bash
pip install 2ndopinion
```

Or from source:
```bash
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:
```json
{
  "mcpServers": {
    "2ndOpinion": {
      "type": "stdio",
      "command": "2ndopinion"
    }
  }
}
```

If you installed from source and `2ndopinion` isn't on your PATH:
```json
{
  "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

```python
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

```python
{
    "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

```bash
# 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
