@genesislcap/ai-assistant 14.419.2 → 14.421.0

package/docs/multi-agent-architecture.md

@@ -1,198 +0,0 @@
-# Multi-Agent Architecture Plan
-
-## Overview
-
-As more flows are added to a single AI assistant, two things degrade:
-
-- **Tool overload** — tool selection accuracy drops significantly beyond ~15–20 tools
-- **Prompt dilution** — longer system prompts cause attention to dilute; instructions buried deep get followed less reliably
-
-The solution is an orchestrating layer that sits between `FoundationAiAssistant` and `ChatDriver`, classifying each user message and routing it to the right specialist — each with its own focused system prompt, tools, and primer. The user sees one chat interface; multiple specialists run underneath.
-
----
-
-## Architecture
-
-```
-User message
-    ↓
-FoundationAiAssistant
-    ↓
-OrchestratingDriver (new)
-    ├─ Classifier  →  picks active AgentConfig
-    └─ ChatDriver  ←  swaps in systemPrompt, tools, primerHistory per turn
-```
-
-### Key design decisions
-
-- **Shared history** — all specialists read and write to the same message array. The settlement specialist can see what the allocations specialist did three turns ago; it just won't try to act like it.
-- **Classification fires once per user turn**, before the tool loop starts. Once a specialist is picked, its config runs for the entire tool loop (which may be many iterations). Specialists do not swap mid-loop.
-- **Primer as context switch** — the primer is already designed to be invisible and prepended to every call. Each specialist has its own primer encoding its identity and behavioral rules. The model gets the right identity injected fresh every turn.
-- **`ChatDriver` unchanged** — the orchestrator updates the driver's config before delegating. No changes required to the existing tool loop, interaction system, or history management.
-
----
-
-## API
-
-### `AgentConfig`
-
-```typescript
-interface AgentConfig {
-  /** Display name shown in the chat header when this agent is active. */
-  name: string;
-
-  /**
-   * Plain-language description of what this agent handles.
-   * Used by the classifier to auto-generate its routing prompt — no manual
-   * classifier prompt authoring needed.
-   */
-  description: string;
-
-  systemPrompt?: string;
-  toolDefinitions?: ChatToolDefinition[];
-  toolHandlers?: ChatToolHandlers;
-  primerHistory?: ChatMessage[];
-}
-```
-
-### Component usage
-
-```html
-<foundation-ai-assistant
-  :agents="${(x) => x.agents}"
-  :chatConfig="${() => ({ ... })}"
->
-```
-
-### Example configuration
-
-```typescript
-agents: AgentConfig[] = [
-  {
-    name: 'Trades Assistant',
-    description: 'Handles trade search, entry, and amendment',
-    systemPrompt: TRADES_SYSTEM_PROMPT,
-    toolDefinitions: createTradesToolDefinitions(),
-    toolHandlers: createTradesToolHandlers(this.connect),
-    primerHistory: tradesAssistantPrimer,
-  },
-  {
-    name: 'Allocations Assistant',
-    description: 'Handles trade allocation across sub-accounts',
-    systemPrompt: ALLOCATIONS_SYSTEM_PROMPT,
-    toolDefinitions: createAllocationsToolDefinitions(),
-    toolHandlers: createAllocationsToolHandlers(this.connect),
-    primerHistory: allocationsAssistantPrimer,
-  },
-];
-```
-
----
-
-## `OrchestratingDriver` (next PR)
-
-Sits between `FoundationAiAssistant` and `ChatDriver`. Implements the same external interface as `ChatDriver` so the component needs no changes.
-
-```
-OrchestratingDriver
-├─ agents: AgentConfig[]
-├─ chatDriver: ChatDriver          (one shared instance)
-├─ activeAgent: AgentConfig        (last classified specialist)
-│
-├─ sendMessage(input, attachments)
-│   1. Classify input → pick AgentConfig
-│   2. Swap systemPrompt, toolDefinitions, toolHandlers, primerHistory on chatDriver
-│   3. Update activeAgent (triggers header name update if changed)
-│   4. Delegate to chatDriver.sendMessage(input, attachments)
-│
-└─ classify(input): Promise<AgentConfig>
-    - Builds a minimal prompt: agent names + descriptions + user message
-    - Single non-tool LLM call (no history needed — cheap and fast)
-    - Returns matched AgentConfig
-```
-
-### Classifier prompt shape
-
-Auto-generated from `AgentConfig.description`. No manual authoring required:
-
-```
-You are a routing classifier. Given a user message, respond with exactly one of the
-following agent names and nothing else.
-
-Agents:
-- Trades Assistant: Handles trade search, entry, and amendment
-- Allocations Assistant: Handles trade allocation across sub-accounts
-- Settlement Assistant: Handles settlement status queries and instructions
-
-User message: "{{userInput}}"
-```
-
-The classifier uses the same `aiProvider` but with minimal context — just the user's message. It is a fraction of the cost of a specialist call.
-
----
-
-## Chat header: active agent name
-
-When multiple agents are configured, the active `AgentConfig.name` drives the displayed title and updates when the specialist changes. `header-title` is a fallback for when no agents are configured.
-
----
-
-## Agent switch indicator
-
-When the active specialist changes mid-conversation, an optional inline system divider can be injected into the message history:
-
-```
-─────────── Allocations Assistant ───────────
-```
-
-Visually distinct from chat bubbles — a small centred metadata marker, not a conversation message.
-
-### Configuration
-
-```typescript
-chatConfig: {
-  showAgentSwitchIndicator?: boolean  // default: false
-}
-```
-
-Also shown automatically when `showToolCalls` is true, on the assumption that users who want to see tool calls also want to see routing decisions.
-
-### Implementation
-
-`OrchestratingDriver` compares the newly classified agent against `activeAgent` after each classification. On a switch, it appends a synthetic message (`role: 'system-event'`, `content: agentConfig.name`) before delegating to `ChatDriver`. The template renders this type as the divider element rather than a chat bubble.
-
----
-
-## Mid-flow handoffs
-
-Classification fires once per turn, before the tool loop. The tricky case: user is halfway through an allocation and asks a cross-domain question before the flow completes.
-
-Options (in order of complexity):
-
-1. **Suppress re-routing while a flow is active** — `OrchestratingDriver` tracks whether the previous turn ended with a pending interaction. If so, hold the current specialist regardless of classification.
-2. **Give the active specialist a narrow fallback tool** — e.g. the allocations specialist has a read-only `get_settlement_status` tool to handle common cross-domain queries without a handoff.
-3. **Ask the user to clarify** — simplest but blunt. Acceptable as a v1 fallback.
-
-Option 1 + 2 together cover most real cases without requiring suspend/resume infrastructure.
-
----
-
-## Status
-
-### Done (this PR)
-
-- [x] `AgentConfig` interface defined in `config/config.ts` and exported from the package
-- [x] `agents?: AgentConfig[]` observable added to `FoundationAiAssistant`
-- [x] Flat props (`systemPrompt`, `toolDefinitions`, `toolHandlers`, `primerHistory`) removed from `FoundationAiAssistant`
-- [x] `connectedCallback` reads from `agents[0]` to feed `ChatDriver` (TODO comment marks where orchestration slots in)
-- [x] `downloadHistory` reads agent name and config from `agents[0]` (TODO comment marks where active agent tracking slots in)
-- [x] Showcase `trades-assistant` template migrated to `:agents` binding
-
-### Next PR
-
-- [ ] Implement `OrchestratingDriver` with classifier and delegation logic
-- [ ] Wire `FoundationAiAssistant` to use `OrchestratingDriver` when `agents.length > 1`
-- [ ] Bind header title to `activeAgent.name` when in multi-agent mode
-- [ ] Add `showAgentSwitchIndicator` to `ChatConfig` and implement the system-event message type + divider template
-- [ ] Write specialist configs for each new domain (allocations, settlement, etc.)
-- [ ] Decide on mid-flow handoff strategy (suppress re-routing vs. fallback tools vs. clarify)