flowchart TD
    subgraph CONTRACT["1. Declarative Research Contract"]
        A["Formal Hypothesis & spec.yaml"] --> B["Declarative Spec Loader"]
        B --> C["Hardware & VRAM Telemetry (Resource Guard)"]
    end

    subgraph AGENTS["2. Multi-Agent Hierarchy (Antigravity SDK / LLM)"]
        C --> D["Mission Planner"]
        D --> E["Experiment Worker (Model Implementation & reproduce.sh)"]
        E --> F["Adversarial Reviewer (Blind Peer Review)"]
        F -- "Data Leakage / Target Failed" --> E
    end

    subgraph SANDBOX["3. External Sandboxed Staging (Zero Pollution)"]
        E -.-> G["~/.research_staging/experiments/EXP_ID/"]
        G -.-> H["src/, artifacts/, logs/, status.json"]
    end

    subgraph PROMOTION["4. Verification Gate & Knowledge Distillation"]
        F -- "VERDICT: CONFIRMED" --> I["Git Promoter (exp/EXP_ID Branch)"]
        I --> J["Target Production Repo (e.g., SpikeNets)"]
        I --> K["Autonomous Skill Distiller (SKILL.md)"]
        I --> L["Zettelkasten & Knowledge Graph Sync (Obsidian + Memory MCP)"]
    end

git clone https://github.com/ijstt/hyra-research.git
cd hyra-research
uv venv
source .venv/bin/activate
uv pip install -e ".[dev,mcp]"

pip install -e ".[dev,mcp]"

# 1. Initialize a new isolated experiment in staging
hyra init EXP-002 --title "Adaptive Threshold SNN" --project SpikeNets

# 2. Run the experiment synchronously
hyra run EXP-002

# 3. Or launch detached execution in the background (leaves terminal free)
hyra run EXP-002 --background

# 4. Check experiment liveness, PID, logs, and audit verdict
hyra status EXP-002

# 5. Promote a confirmed experiment to target Git repository on a new branch
hyra promote EXP-002

# 6. Distill a verified algorithm into a permanent agent skill
hyra distill \
  --name fast_laplace_solver \
  --desc "High-performance Gaver-Stehfest numerical Laplace inverter" \
  --guide "Use when computing first passage times for continuous SDEs." \
  --example path/to/solver.py

{
  "mcpServers": {
    "hyra-research": {
      "command": "hyra-mcp",
      "args": [],
      "env": {
        "HYRA_STAGING_DIR": "/home/user/.research_staging",
        "HYRA_DEFAULT_PROJECT": "/home/user/SpikeNets"
      }
    }
  }
}

experiment_id: "EXP-001"
title: "Exponential Leaky Integrate-and-Fire with Dynamic Adaptive Threshold"
project_path: "/home/user/SpikeNets"
date: "2026-11-02"

hypothesis:
  statement: "Adaptive membrane thresholds mitigate high-frequency false positives while maintaining precision >= 95%."
  mathematical_formulation: |
    dV_t = -(V_t - V_rest) / tau_m * dt + R * I_t * dt + sigma * dW_t
    dTheta_t = -(Theta_t - Theta_0) / tau_theta * dt + delta_theta * dS_t

falsification:
  target_metric: "f1_score"
  baseline_metric: 0.812
  required_gain: 0.05       # Minimum 5% relative improvement
  max_p_value: 0.01         # Statistical significance requirement
  numerical_stability_check: true

compute_budget:
  max_runtime_minutes: 60
  gpu_memory_limit_mb: 8192
  allow_cpu_fallback: false
  random_seeds: [42, 137, 2026]

execution_steps:
  - "1. Synthesize benchmark data without future look-ahead"
  - "2. Evaluate baseline LIF model and store artifacts"
  - "3. Implement adaptive dynamic threshold LIF"
  - "4. Run cross-validation over fixed seeds"
  - "5. Output reproduce.sh and invoke adversarial reviewer"

promotion:
  target_module_path: "spikenets/models/adaptive_lif.py"
  target_notebook_path: "notebooks/demo_adaptive_lif.ipynb"

# Run test suite
pytest tests -v

hyra-research/
├── src/
│   └── hyra/
│       ├── __init__.py          # Public API exports
│       ├── cli.py               # Unified CLI interface (hyra)
│       ├── config.py            # Dynamic configuration and environment manager
│       ├── engine.py            # Multi-agent orchestrator (Antigravity SDK / LLM)
│       ├── mcp_server.py        # Model Context Protocol stdio server
│       ├── promoter.py          # Git promotion gate and verification engine
│       ├── resource_guard.py    # Hardware telemetry and sandboxed process runner
│       ├── scaffolding.py       # Isolated workspace initialization
│       ├── skill_distiller.py   # Autonomous skill compiler (SKILL.md)
│       └── spec_loader.py       # YAML contract validation
├── templates/
│   ├── spec_template.yaml       # Canonical declarative contract template
│   └── experiment_card.md       # Obsidian Zettelkasten experiment card template
├── examples/
│   └── exp_001_snn_baseline/    # End-to-end reproducible experiment reference
├── tests/
│   ├── test_config.py
│   ├── test_promoter.py
│   ├── test_resource_guard.py
│   ├── test_scaffolding.py
│   ├── test_skill_distiller.py
│   └── test_spec_loader.py
├── pyproject.toml               # PEP 621 package build configuration
├── README.md                    # Platform documentation and architecture
└── LICENSE                      # MIT License