# Fusion Symphony

> Multi-Model Fusion Orchestrator — a DSH (DeepSeek Harness) plugin package that runs MoA-style fusion over DSH's own registered LLM providers, **zero training**.
>
> `pluginId = fusion-symphony` · registers tool `fusion_symphony_orchestrate`

[中文版 README](./README.md)

## What it is

Fusion Symphony unifies the strengths of three fusion paradigms — OpenRouter Fusion (static panels + synthesis), Sakana Fugu Ultra (dynamic orchestration + multi-round verification), and Hermes MoA (advisor parallelism with the main agent holding the tools) — into **one engine with three configurable axes** (topology × tool permissions × verification loop), replacing the trained orchestrator with pure prompt-driven orchestration. All model calls go through DSH's registered `ctx.llm` providers (e.g. deepseek / pi-ai / an OpenRouter gateway), so no external gateway is required.

## Implementation form

- A real DSH plugin is a **bundle package**: `package.json` declares `dsh.bundle.patch` → `cordis.patch.yml`, which inserts the plugin entry into the Cordis composition; the plugin module exports `{ name, inject, Config, apply(ctx, config) }`.
- Tools are registered via `ctx.tools.register(defineTool({ ... }))` (from `@deepseek-ai/dsh-tools`).
- Model calls use `ctx.llm` (`@deepseek-ai/dsh-llm`); evidence retrieval uses `ctx.web.search`.

## Directory layout

```
Plugins/fusion-symphony/
├── package.json          # bundle declaration + entry
├── cordis.patch.yml      # inserts the plugin entry into a profile composition
├── lib/
│   ├── index.js          # plugin + orchestrate tool registration + engine
│   ├── llm.js            # ctx.llm model calls + ctx.web search wrapper
│   ├── prompts.js        # Gate/Conductor/Worker/Verifier/Framing prompts + JSON extraction
│   └── types/index.d.ts  # public types
├── test/
│   ├── smoke.mjs         # offline end-to-end smoke suite (npm test)
│   └── install-check.mjs # validates the bundle composition via DSH's loadProfile
└── README.md / README.en.md
```

## Install (into a DSH profile)

```bash
# From any cwd; relative path specs are anchored to the invoking directory
dsh plugin --profile default add file:/path/to/fusion-symphony
# Windows example:  dsh plugin --profile default add file:D:\work\...\fusion-symphony
```

`dsh plugin add` installs the package with pnpm into the profile and — because this package declares `dsh.bundle` — appends it to `dsh.profile.bundles`. On the next profile boot, `cordis.patch.yml` inserts the `fusion-symphony` entry.

> Note: the bundle/patch mechanism applies to `dsh --profile <name>` profiles. Replace `default` with your actual profile name.

## Configuration (`cordis.patch.yml` `config`; can be changed after install or overridden per call via tool arguments)

| Field | Default | Description |
|---|---|---|
| `enabled` | `true` | Whether to register the tool |
| `provider` | `deepseek-official` | Default provider route (verified against the deployment: `settings.yaml` + the `@deepseek-ai/dsh-llm-deepseek` adapter) |
| `model` | `deepseek-v4-flash` | Default model id |
| `conductorModel` | `""` | Model id for the gate/conductor (empty = use `model`) |
| `aggregatorModel` | `""` | Model id for the verifier/framing call (empty = use `model`) |
| `workerModels` | `["deepseek-v4-flash", "deepseek-v4-pro"]` | Worker model id list (multiple models on one provider = real fusion; under auto/fugu the first half are advisors, the rest agents) |
| `advisors` / `agents` | `2` / `2` | Default advisor/agent counts |
| `search` | `true` | Whether agent-role workers may use `web_search` for evidence |
| `useConductor` | `false` | Reserved switch (see Known limitations) |
| `processBriefing` | `true` | Inject a "fusion process briefing" context message after every call (worker claims, evidence sources, verdict); set `false` to disable |
| `maxRounds` | `2` | Verification / deepen-round cap |
| `maxWorkers` | `4` | Concurrency cap (batch size) |
| `maxTotalToolCalls` | `8` | Tool-call budget (reserved) |
| `maxTokensPerWorker` | `4000` | Per-worker maxTokens (floored at 16000 in practice) |
| `maxTokensAggregator` | `16000` | Framing-call output cap |
| `maxSections` | `8` | Safety ceiling on chapters; the conductor decides the actual count per task (surveys 6+, simple tasks 1–2) |

**Key to real fusion**: put multiple different model ids in `workerModels` (or pass `worker_models` per call, possibly across providers) — that is what lets different models' blind spots cancel out. With a single model the plugin degrades to same-model multi-role MoA.

## Invocation

```
fusion_symphony_orchestrate
  query: "What was the official latest market-size figure for industry X in 2026?"
  preset: "auto"             # auto|fusion|hermes|fugu
  return_mode: "synthesized" # or materials (Hermes-style: hand the claims+verdict back to the host agent)
  worker_models: [{provider:"openrouter",model:"anthropic/claude-...",role:"agent"},
                  {provider:"openrouter",model:"openai/gpt-...",role:"agent"},
                  {provider:"openrouter",model:"google/gemini-...",role:"advisor"}]
```

Returns: `{ status, final_answer, divergence_report, summary, materials?, error? }`.

`final_answer` is the **complete assembled report** (framing + every chapter draft verbatim, no compression) — write it to the file as-is.

## Preset semantics

| preset | topology | tools | verification | return |
|---|---|---|---|---|
| `fusion` | all agents | yes | single round + framing | synthesized |
| `hermes` | all advisors | no | single round | materials |
| `fugu` / `auto` | mixed | by role | multi-round verify + deepen | synthesized |

## Design highlights

- **Zero training**: Conductor / Worker / Verifier / Framing are all prompt roles — no weight updates anywhere.
- **Task-adaptive decomposition (Conductor)**: the conductor decides the chapter count for each task (`maxSections` is only a safety ceiling); workers write chapters in batches (batch size = worker count), no length limit ("write until the chapter's points are fully developed; 3000+ chars is the goal").
- **Evidence ledger**: every agent-role claim carries its `evidence` (raw retrieval results).
- **Depth verification**: the verifier checks coverage AND depth (each sub-task must have real substance ≥800 chars); shallow chapters trigger a targeted deepen round.
- **Scope-shrinking deepen**: re-dispatch only targets the flagged chapter with an explicit request — cost stays bounded.
- **Zero-compression assembly (report length is not capped by any single call)**: the aggregator produces only the framing layer (title / abstract / TOC / overview / conclusion, one lightweight call); the plugin concatenates every chapter draft **verbatim** into `final_answer` (`## chapter title` sections). Report length = Σ chapter lengths. Full chapter drafts also ride along in `materials`.
- **Degradation chain**: all workers failed → single-model direct answer (L2); verifier/framing failure → flagged `unverified` (L3).
- **Untrained-conductor reliability**: structured JSON extraction + graceful fallback to whole-task workers.

## Observability

- **Process briefing injection**: after each call the tool injects a "fusion process briefing" context message via `exec.deferContext` (controlled by `processBriefing`) — per-worker claim summaries, evidence sources, verifier verdict, round statistics — visible in the conversation and written to the session log.
- **Custom cards**: `presentCall` (pending card shows `fusion-symphony · <preset>` + query) and `presentResult` (completed card shows status and stats: rounds / workers / models / divergence count), projected through `output.presentationMeta` and replayable from the session log.
- The returned `summary` (rounds / workersUsed / models / fallbackLevel) is the execution-statistics view.

## Verified interfaces (from the local DSH checkout sources)

- `defineTool({ name, description, parameters, output:{schema,render}, timeoutMs, isConcurrencySafe, execute(args, exec) })` (`@deepseek-ai/dsh-tools`)
- `ctx.tools.register(definition)`, `ctx.systemPrompt.section({name,order,text})`
- `ctx.llm.stream({ provider, model, messages, system, temperature, maxTokens, signal })` + `BlockAssembler.blocks()` (`@deepseek-ai/dsh-llm`)
- `ctx.web.search({ query, maxResults }, signal)` (`@deepseek-ai/dsh-web`)
- Cordis bundle: `dsh.bundle.patch` → `cordis.patch.yml` (`insert` list, `@deepseek-ai/cordis-plugin-include`)

## Known limitations

- Verified by the offline smoke suite (`npm test` — a scripted mock LLM drives the real `execute` pipeline) plus the install check (`npm run test:install` — validates the bundle composition with DSH's own `loadProfile`). **Live in-conversation verification still requires a Web GUI (web profile) restart, then one real call** (it consumes real `deepseek-official` API quota).
- `maxTotalToolCalls` / `est_cost_usd` are approximate / not billed (no price table).
- `useConductor` is a reserved switch: the full "Conductor dynamic Plan" is not wired in yet; the current engine implements the equivalent skeleton via static decomposition + verify/deepen.
- With a single model, fusion gains shrink (you need multiple model routes to see the difference); the default pool is flash + pro, two real models.

## Development

```bash
npm install        # install deps (creates node_modules)
npm test           # offline smoke suite (all paths, output-schema-validated)
npm run test:install  # optional: validate bundle composition (needs DSH_APP_PACKAGE_JSON)
```

## License

MIT — see [LICENSE](./LICENSE).