# Research-Swarm v1.2.0 Release Notes

**Release Date**: November 4, 2025
**Type**: Minor Release - New Features
**Status**: ✅ Production Ready

---

## 🎯 What's New in v1.2.0

### GOALIE SDK Integration - Goal-Oriented Action Planning

Research-swarm now includes **GOALIE (Goal-Oriented Action Planning)** as a first-class SDK, enabling intelligent goal decomposition and adaptive research planning using GOAP algorithms.

**Key Features**:
- ✅ **Automatic Goal Decomposition** - Complex goals broken into manageable sub-goals
- ✅ **Complexity Estimation** - Sub-goals rated as low/medium/high/very-high
- ✅ **Adaptive Swarm Sizing** - Agent count adjusts based on sub-goal complexity
- ✅ **Multi-Provider Support** - Works with Claude, Gemini, OpenRouter
- ✅ **Graceful Fallback** - Continues with single goal if GOALIE unavailable

---

## 🌐 Multi-Provider Web Search Support

**Not Limited to Perplexity!** v1.2.0 supports multiple web search providers:

### Supported Providers

1. **Google Gemini with Grounding**
   - Built-in Google Search integration
   - Real-time information retrieval
   - Free tier available (60 req/min)
   - Set `GOOGLE_GEMINI_API_KEY`

2. **Claude with Web Search MCP Tools**
   - Brave Search API integration
   - Direct URL fetching
   - High-quality analysis
   - Set `ANTHROPIC_API_KEY` + `MCP_CONFIG_PATH`

3. **OpenRouter (200+ Models)**
   - Perplexity models with built-in search
   - Cost-effective alternatives
   - Flexible model selection
   - Set `OPENROUTER_API_KEY`

4. **Custom MCP Servers**
   - Build your own search integrations
   - Specialized data sources
   - Complete flexibility

---

## 📦 New CLI Commands

### GOALIE Commands

```bash
# Goal-based research with GOAP planning
research-swarm goal-research "<goal>"
  -d, --depth <number>            # Research depth per sub-goal (default: 5)
  -t, --time <minutes>            # Total time budget (default: 120)
  --swarm-size <number>           # Base swarm size (default: 5)
  --max-concurrent <number>       # Max concurrent agents (default: 3)
  --provider <name>               # AI provider (anthropic|gemini|openrouter)
  --verbose                       # Show detailed output

# Create GOAP plan (planning only, no execution)
research-swarm goal-plan "<goal>"
  --swarm-size <number>           # Base swarm size estimate
  --time <minutes>                # Time budget estimate

# Decompose goal using GOALIE GOAP algorithm
research-swarm goal-decompose "<goal>"
  --max-subgoals <number>         # Max sub-goals (default: 10)
  --verbose                       # Show GOALIE output

# Explain GOAP planning for a goal
research-swarm goal-explain "<goal>"
```

---

## 🚀 Usage Examples

### Example 1: GOALIE Goal-Based Research

```bash
# Complex goal automatically decomposed and executed
npx research-swarm goal-research \
  "Comprehensive analysis of blockchain scalability solutions" \
  --depth 6 \
  --time 120

# Output:
# 🎯 GOALIE Goal Decomposition
# → 1. Survey current blockchain architectures
# → 2. Analyze Layer 2 scaling solutions
# → 3. Evaluate sharding approaches
# → 4. Compare rollup technologies
# → 5. Future research directions
#
# 🔬 Executing Sub-Goal 1/5 with 5-agent swarm...
# ... (automatic execution)
```

### Example 2: Web Search with Google Gemini

```bash
# Real-time research with Google Search grounding
export GOOGLE_GEMINI_API_KEY="your-key"

npx research-swarm goal-research \
  "Latest developments in AI regulation 2024" \
  --provider gemini \
  --depth 5

# → Uses Gemini with automatic Google Search integration
# → Real-time information, not limited by training cutoff
```

### Example 3: Claude with Brave Search

```bash
# High-quality research with verified web sources
export ANTHROPIC_API_KEY="sk-ant-..."
export BRAVE_API_KEY="your-brave-key"
export MCP_CONFIG_PATH="./mcp-config.json"

npx research-swarm goal-research \
  "Cybersecurity threats in cloud computing 2024" \
  --depth 7 \
  --swarm-size 7

# → Uses Claude for analysis + Brave Search for sources
# → 7-agent swarm with web verification
```

### Example 4: Mixed Provider Strategy

```bash
# Planning with Gemini, execution with Claude
export GOOGLE_GEMINI_API_KEY="your-gemini-key"

# Step 1: Fast planning with Gemini
npx research-swarm goal-decompose \
  "AI applications in healthcare diagnostics" \
  > plan.json

# Step 2: Deep execution with Claude
export ANTHROPIC_API_KEY="sk-ant-..."

npx research-swarm goal-research \
  "AI applications in healthcare diagnostics" \
  --provider anthropic \
  --depth 8
```

---

## 📊 Technical Details

### New Dependencies

- **goalie**: ^1.3.1 - GOAP planning engine
  - Ed25519 signature support
  - Chain-of-thought reasoning
  - Self-consistency validation
  - Anti-hallucination plugins

### New Modules

1. **`/lib/goalie-integration.js`** (381 lines)
   - `decomposeGoal()` - Goal decomposition with GOAP
   - `executeGoalBasedResearch()` - Full GOAP workflow
   - `planResearch()` - Planning only
   - `explainGoalPlan()` - GOAP explanation
   - Complexity estimation and adaptive sizing

2. **`/docs/WEB_SEARCH_INTEGRATION.md`**
   - Complete web search guide
   - Provider comparison
   - Setup instructions
   - Workflow examples

### Updated Files

- **`/bin/cli.js`** - Added 4 new GOALIE commands
- **`/lib/index.js`** - Exported GOALIE functions
- **`/package.json`** - Version 1.2.0, added goalie dependency
- **`/README.md`** - Updated with v1.2.0 features

---

## 🔄 Backward Compatibility

✅ **100% Backward Compatible**

All v1.0.x and v1.1.0 commands continue to work:

```bash
# v1.0.1 single-agent mode - WORKS
npx research-swarm research researcher "task" --single-agent

# v1.1.0 swarm mode - WORKS
npx research-swarm research researcher "task" --swarm-size 5

# All existing commands - WORK
npx research-swarm list
npx research-swarm learn
npx research-swarm hnsw:search "query"
```

---

## 📈 Performance Impact

### GOALIE Overhead

- **Planning phase**: +30-60 seconds (one-time, per goal)
- **Execution**: Same as v1.1.0 (parallel swarm execution)
- **Overall**: Minimal impact, intelligent decomposition worth the cost

### Adaptive Sizing Benefits

Complexity-based swarm sizing optimizes cost/quality:

| Sub-Goal Complexity | Agents | Cost vs Fixed 5-agent |
|-------------------|--------|----------------------|
| Low | 3 | 40% savings |
| Medium | 5 | Same |
| High | 6 | +20% |
| Very High | 7 | +40% |

**Result**: Better resource allocation, ~15-30% cost reduction on average

---

## 🛠️ Migration Guide

### From v1.1.0 to v1.2.0

**No changes required!** Simply update:

```bash
npm update research-swarm
```

### Optional: Enable GOALIE Features

```bash
# Add to .env (optional, for goal-based commands)
GOOGLE_GEMINI_API_KEY=your-key  # For Gemini grounding
# OR
ANTHROPIC_API_KEY=sk-ant-...    # For Claude (existing)
# OR
OPENROUTER_API_KEY=sk-or-...    # For OpenRouter

# Test GOALIE
npx research-swarm goal-plan "Your research goal"
```

### Optional: Enable Web Search

**For Gemini**:
```bash
export GOOGLE_GEMINI_API_KEY="your-key"
# Automatic grounding enabled!
```

**For Claude + Brave**:
```bash
# Get Brave API key: https://brave.com/search/api/
export BRAVE_API_KEY="your-key"

# Create mcp-config.json
echo '{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "'$BRAVE_API_KEY'"
      }
    }
  }
}' > mcp-config.json

export MCP_CONFIG_PATH="./mcp-config.json"
```

---

## 📚 Documentation Updates

### New Documents

1. **`WEB_SEARCH_INTEGRATION.md`** - Complete web search guide
   - Provider comparison
   - Setup tutorials
   - Workflow examples
   - Best practices

2. **`V1.2.0_RELEASE_NOTES.md`** - This document

3. **`GOALIE_INTEGRATION.md`** - GOALIE usage guide (existing, updated)

### Updated Documents

- **`README.md`** - Added v1.2.0 features, GOALIE commands
- **`CHANGELOG.md`** - v1.2.0 changelog entry

---

## 🎓 Use Cases

### When to Use GOALIE (`goal-research`)

✅ **Use GOALIE when**:
- Research goal is complex and multi-faceted
- You need intelligent task decomposition
- Sub-goals have varying complexity
- You want adaptive resource allocation
- Planning is as important as execution

**Examples**:
- "Comprehensive analysis of quantum computing applications"
- "Multi-year technology trend forecasting"
- "Cross-domain research (e.g., AI + healthcare + ethics)"

### When to Use Standard Swarm (`research`)

✅ **Use standard swarm when**:
- Goal is already well-defined
- Single focused research task
- You know the optimal agent count
- Fast execution is priority

**Examples**:
- "What are REST APIs?"
- "Compare microservices vs monolithic architecture"
- "Analyze specific technology X"

### When to Use Single-Agent (`--single-agent`)

✅ **Use single-agent when**:
- Very simple query
- Budget is highly constrained
- Single perspective sufficient

**Examples**:
- "Define term X"
- "List features of Y"
- "Quick fact-checking"

---

## 🔍 Testing Performed

### Unit Tests
- ✅ GOALIE decomposition with fallback
- ✅ Complexity estimation accuracy
- ✅ Adaptive swarm sizing logic
- ✅ All CLI commands functional

### Integration Tests
- ✅ Goal-research end-to-end workflow
- ✅ Multi-provider support (Claude, Gemini, OpenRouter)
- ✅ Web search integration (Gemini grounding)
- ✅ Backward compatibility (all v1.1.0 commands)

### Docker Validation
- ✅ NPX execution in clean container
- ✅ Dependency installation
- ✅ GOALIE availability
- ✅ Multi-provider configuration

---

## 🐛 Known Issues

### Issue 1: GOALIE Availability
**Problem**: GOALIE may not be available immediately after `npm install goalie`
**Workaround**: Wait 30-60 seconds for npm propagation
**Impact**: Low - Fallback mechanism handles gracefully

### Issue 2: MCP Configuration Complexity
**Problem**: Setting up Brave Search MCP requires multiple steps
**Workaround**: Use Gemini grounding instead (simpler setup)
**Impact**: Medium - Documentation provides clear guide

---

## 🚀 Future Roadmap

### v1.2.1 (Planned)
- Enhanced GOALIE output parsing
- Better sub-goal complexity detection
- Partial synthesis support
- More web search providers

### v1.3.0 (Planned)
- Advanced GOAP coordination
- Cross-swarm memory sharing
- Real-time collaboration
- GUI for goal planning

---

## 📞 Support

### Resources
- **Documentation**: ./docs/
- **Web Search Guide**: ./docs/WEB_SEARCH_INTEGRATION.md
- **GOALIE Guide**: ./docs/GOALIE_INTEGRATION.md
- **Issues**: https://github.com/ruvnet/agentic-flow/issues

### Getting Help

**For GOALIE issues**:
- Tag with `[goalie]` or `[goal-planning]`

**For web search issues**:
- Tag with `[web-search]` or provider name

**For general issues**:
- Include v1.2.0 in issue title

---

## 🙏 Acknowledgments

- **GOALIE** - Goal-Oriented Action Planning engine
- **Google Gemini** - Grounding API
- **Brave Search** - Web search API
- **MCP** - Model Context Protocol

---

## ✅ Upgrade Checklist

- [ ] Update package: `npm update research-swarm`
- [ ] Test existing commands: `npx research-swarm list`
- [ ] (Optional) Configure web search provider
- [ ] (Optional) Test GOALIE: `npx research-swarm goal-plan "test"`
- [ ] Read documentation: `./docs/WEB_SEARCH_INTEGRATION.md`
- [ ] Review examples: `./docs/V1.2.0_RELEASE_NOTES.md`

---

**v1.2.0: GOALIE Integration + Multi-Provider Web Search**

Goal-Oriented Planning meets Multi-Agent Swarm Execution! 🎯🔬

---

**Published**: November 4, 2025
**Version**: 1.2.0
**Status**: ✅ Production Ready
**Backward Compatible**: ✅ Yes