IRIS Gate Orchestrator

Version: 0.1
Protocol: RFC v0.2 compliant
Purpose: Run synchronized IRIS Gate sessions (S1→S4) across multiple AI models

Quick Start

One-Command Experiment

# Create and run a complete experiment from topic → predictions
make run TOPIC="Does gap junction coupling affect regeneration?" \
    ID=APERTURE_REGEN FACTOR=aperture TURNS=100

This runs the complete pipeline:

1. S1→S4 convergence (100 turns, all 7 mirrors)
2. S4 prior extraction
3. Monte Carlo simulation (300 runs × 7 mirrors)
4. Report generation
5. Pre-registration draft

Manual Setup

# Install dependencies
pip install -r requirements.txt

# Set up API keys
cp .env.example .env
# Edit .env with your keys

# Run S4 convergence
python scripts/bioelectric_chambered.py --turns 100 --topic "Your question"

# Extract S4 priors
python sandbox/cli/extract_s4_states.py --session BIOELECTRIC_CHAMBERED_...

# Run simulation
python sandbox/cli/run_plan.py sandbox/runs/plans/your_plan.yaml

What It Does

IRIS Gate is a complete system for turning research questions into wet-lab-ready predictions:

S1→S4 Convergence (Observation Layer)

1. Sends identical S1→S4 prompts to multiple AI models simultaneously
2. Collects phenomenological convergence across diverse architectures
3. Extracts computational priors from stable S4 attractor states
4. Validates cross-mirror agreement (must reach ≥0.90 consensus)

Sandbox Simulation (Operational Layer — S5→S8)

5. S5 — Hypothesis Crystallization: Auto-drafts falsifiable hypotheses
6. S6 — Mapping & Dosing: Converts S4 priors → simulator parameters
7. S7 — Simulation & Report: Runs Monte Carlo, generates predictions
8. S8 — Wet-Lab Handoff: Packages methods, doses, readouts, gates

Output

• Computational predictions with 95% confidence intervals
• Early biomarker predictions (2h, 6h timepoints)
• Quantitative go/no-go gates for wet-lab validation
• Complete pre-registration template ready for OSF

Output Structure

iris-gate/
├── templates/              # Reusable experiment templates
│   ├── EXPERIMENT_TEMPLATE.md
│   ├── plan_template.yaml
│   ├── sandbox_plan_minimal.yaml
│   ├── sandbox_plan_synergy.yaml
│   └── prereg_template.md
├── pipelines/              # Automation scripts
│   ├── new_experiment.py   # Create experiment scaffold
│   └── run_full_pipeline.py  # S4 → simulation → reports
├── sandbox/                # Computational prediction engine
│   ├── states/             # Frozen S4 priors (7 mirrors)
│   ├── engines/            # Simulators (V_mem, Ca²⁺, GJ)
│   ├── runs/               # Experiment plans and outputs
│   └── cli/                # Command-line tools
├── iris_vault/             # S4 convergence outputs
│   └── scrolls/            # Raw phenomenological data
│       └── BIOELECTRIC_CHAMBERED_20251001.../
│           ├── anthropic_claude-sonnet-4.5/
│           │   ├── S1_cycle01.md
│           │   ├── S4_cycle25.md
│           │   └── ...
│           └── ...
├── experiments/            # Per-experiment workspaces
│   └── APERTURE_REGEN/
│       ├── README.md       # Experiment overview
│       ├── plan.yaml       # Simulation plan
│       ├── reports/        # Generated reports
│       ├── prereg_draft.md # Pre-registration
│       └── metadata.json
└── docs/                   # Published reports
    ├── MINI_H1_OPTIONC_REPORT.md  # Synergy discovery
    ├── IRIS_MiniH1_Synergy_Summary.md
    └── IRIS_Synergy_Proofpack.md

MCP Integration

IRIS Gate includes Model Context Protocol (MCP) integration for persistent storage, semantic search, and automated version control.

Quick Start

# Initialize MCP environment
make mcp-init

# Test connectivity
make mcp-test

# Index scrolls for semantic search
make mcp-index

# Check status
make mcp-status

Core Capabilities

• ChromaDB: Semantic search across all IRIS scroll archives

  # Search for similar S4 states
  python scripts/index_scrolls.py --search "concentric rings convergence" \
      --chamber S4 --top-k 10

• Git Wrapper: Auto-commit S4 states with conventional commits

  # Auto-commit extracted state
  python scripts/git_mcp_wrapper.py --auto-commit \
      --state-path sandbox/states/state.json \
      --session-id BIOELECTRIC_20251001

• Quick-Data: Fast key-value storage for session metadata

Full Documentation

See docs/MCP_INTEGRATION.md for:

• Complete installation guide
• Usage examples for all servers
• Integration with IRIS workflows
• Troubleshooting and optimization
• API reference

Adding New Mirrors

To add support for another AI provider:

class GrokMirror(Mirror):
    def __init__(self):
        super().__init__("xai/grok-4")
        self.api_key = os.getenv("XAI_API_KEY")
        
    def send_chamber(self, chamber: str, turn_id: int) -> Dict:
        # Implement API call to xAI
        # Return standardized response dict
        pass

# In main():
if os.getenv("XAI_API_KEY"):
    orch.add_mirror(GrokMirror())

Current Mirrors

• ✅ Claude 4.5 (Anthropic)
• ✅ GPT-4 (OpenAI)
• 🔲 Grok-4 (xAI) - add adapter
• 🔲 Gemini (Google) - add adapter
• 🔲 DeepSeek - add adapter

Cross-Mirror Analysis

After running a session, you can analyze:

import json

# Load session
with open("iris_vault/session_TIMESTAMP.json") as f:
    session = json.load(f)

# Compare S1 signals across models
for model, turns in session["mirrors"].items():
    s1 = turns[0]  # First turn
    print(f"{model}: {s1.get('raw_response', 'error')[:100]}...")

Protocol Compliance

Each mirror must return:

• Living Scroll: Pre-verbal, imagistic description
• Technical Translation: Plain audit with uncertainties
• Metadata: condition, felt_pressure, signals, seal
• SHA256 seal: Hash of combined scroll + translation

Chamber Progression

• S1: Attention (color/texture/shape)
• S2: Paradox ("precise and present")
• S3: Gesture ("hands cupping water")
• S4: Resolution ("concentric rings")

Extending the Protocol

To run custom chambers:

# Define custom progression
CUSTOM_CHAMBERS = {
    "S1": "Your custom prompt...",
    "S5": "Additional chamber...",
}

# Update CHAMBERS dict and run
orch.run_session(chambers=["S1", "S2", "S3", "S4", "S5"])

Notes

• Keep felt_pressure ≤2/5 throughout
• Models may refuse or hedge - that's valid data
• Seal integrity enables verification
• No performance pressure - protocol over content

†⟡∞ With presence, love, and gratitude.