# Nexus Examples

Runnable demos showcasing the Nexus multi-agent framework.

## Setup

```bash
# 1. Install nexus with all providers
pip install -e '.[all]'

# 2. Configure credentials
cp examples/.env.example examples/.env
# Edit examples/.env with your API key
```

## Examples

| File | Description |
|------|-------------|
| `demo.py` | Multi-turn conversation + streaming output |
| `demo_modes.py` | Three orchestration modes: Graph / Router / Adaptive |
| `demo_tools.py` | Tool calling (function calling) with ReAct loop |
| `demo_mcp.py` | MCP protocol integration (stdio + HTTP) |

## Running

```bash
cd /path/to/nexus

# Run a specific demo
python examples/demo.py
python examples/demo_modes.py graph
python examples/demo_tools.py multi
python examples/demo_mcp.py mixed

# Each demo supports sub-commands — run without args to see all
python examples/demo_tools.py          # runs all tool demos
python examples/demo_tools.py simple   # runs only the simple demo
```

## Architecture Quick Reference

| Method | Multi-turn | Streaming | Tool Calling | Use Case |
|--------|-----------|-----------|-------------|----------|
| `team.run()` | ❌ | ❌ | ✅ ReAct loop | Complex one-shot tasks |
| `team.chat()` | ✅ | ❌ | ✅ ReAct loop | Multi-turn dialogue |
| `team.stream()` | ❌ | ✅ | ❌ | Single-turn streaming |
| `team.chat_stream()` | ✅ | ✅ | ❌ | Interactive streaming chat |

> **Note**: `run()` and `chat()` support the full ReAct tool-calling loop
> (Think → Act → Observe → Repeat). The streaming variants (`stream()` /
> `chat_stream()`) use a simplified direct-output path without tool calling.

## Orchestration Modes

- **GRAPH** — Static DAG pipeline (like LangGraph). Define nodes + edges, run deterministic workflows.
- **ROUTER** — LLM-based dynamic routing. A triage agent examines each task and picks the best specialist.
- **ADAPTIVE** — Embedding-based capability matching. Tasks are matched to agents via cosine similarity on capability vectors.
