diff --git a/plan2.1.md b/plan2.1.md new file mode 100644 index 0000000..88299f7 --- /dev/null +++ b/plan2.1.md @@ -0,0 +1,419 @@ +Hier is een zo uitgebreid mogelijk C++23-skeleton voor de Root Router. Alles wat je redelijkerwijs zelf kunt bouwen zit erin: meerdere routing-strategieën, embedding-cache, session-state, audit-hooks, multi-tenancy, fallback-keten, structured routing-resultaat, parallelle pre-checks en duidelijke extensiepunten. Geen externe libraries. + +```cpp +// agent/root_router.hpp +#pragma once + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include // C++23 + +namespace molo::agent { + +// --------------------------------------------------------------------------- +// Basis types +// --------------------------------------------------------------------------- + +struct Message { + enum class Role { System, User, Assistant, Tool }; + Role role = Role::User; + std::string content; + std::string name; + std::string tool_call_id; + std::chrono::system_clock::time_point timestamp = std::chrono::system_clock::now(); +}; + +struct AgentContext { + std::string session_id; + std::string tenant_id; + std::string user_id; + std::vector messages; + std::unordered_map state; // session state + std::unordered_map metadata; + + // hooks (optioneel invullen vanuit je ORM/session/audit) + std::function audit; + std::function persist_state; +}; + +struct AgentResult { + std::string content; + bool success = true; + std::string error; + std::string routed_to; // welke domain het werd + double routing_confidence = 0.0; + std::string routing_method; // "rules", "embedding", "llm", "fallback" + std::chrono::microseconds routing_latency{0}; + // later: tool_calls, usage, etc. +}; + +class Agent { +public: + virtual ~Agent() = default; + virtual std::string_view name() const = 0; + virtual std::string_view description() const = 0; + virtual std::vector keywords() const { return {}; } // optioneel + virtual AgentResult run(AgentContext& ctx) = 0; +}; + +// --------------------------------------------------------------------------- +// Embedding interface (implementeer met je bestaande client) +// --------------------------------------------------------------------------- + +struct Embedding { + std::vector values; + static float cosine(const Embedding& a, const Embedding& b) { + if (a.values.size() != b.values.size() || a.values.empty()) return 0.0f; + float dot = 0.0f, na = 0.0f, nb = 0.0f; + for (size_t i = 0; i < a.values.size(); ++i) { + dot += a.values[i] * b.values[i]; + na += a.values[i] * a.values[i]; + nb += b.values[i] * b.values[i]; + } + if (na == 0.0f || nb == 0.0f) return 0.0f; + return dot / (std::sqrt(na) * std::sqrt(nb)); + } +}; + +class EmbeddingProvider { +public: + virtual ~EmbeddingProvider() = default; + virtual std::expected embed(std::string_view text) = 0; +}; + +// --------------------------------------------------------------------------- +// Root Router +// --------------------------------------------------------------------------- + +class RootRouter : public Agent { +public: + struct Config { + float embedding_threshold = 0.72f; + bool enable_embedding = true; + bool enable_llm_fallback = false; // later inschakelen + size_t max_recent_messages_for_routing = 3; + std::string default_domain = "llm"; // fallback + }; + + RootRouter(std::vector> domains, + std::shared_ptr embedder = nullptr, + Config cfg = {}) + : domains_(std::move(domains)) + , embedder_(std::move(embedder)) + , config_(cfg) + { + rebuild_index(); + } + + std::string_view name() const override { return "root"; } + std::string_view description() const override { + return "Front-door hierarchical orchestrator with multi-strategy routing"; + } + + AgentResult run(AgentContext& ctx) override { + auto start = std::chrono::steady_clock::now(); + + if (ctx.messages.empty()) { + return fail("empty messages"); + } + + // Neem recente user-content voor routing + std::string routing_text = extract_routing_text(ctx); + + auto decision = decide(ctx, routing_text); + + auto latency = std::chrono::duration_cast( + std::chrono::steady_clock::now() - start); + + if (!decision.agent) { + AgentResult r = fail("no domain matched"); + r.routing_latency = latency; + audit(ctx, "routing_failed", routing_text); + return r; + } + + audit(ctx, "routed", std::string(decision.agent->name()) + " via " + decision.method); + + // Agent-as-tool: parent blijft in control + auto result = decision.agent->run(ctx); + result.routed_to = std::string(decision.agent->name()); + result.routing_confidence = decision.confidence; + result.routing_method = decision.method; + result.routing_latency = latency; + + // Optioneel state persist + if (ctx.persist_state) { + ctx.persist_state("last_domain", result.routed_to); + ctx.persist_state("last_routing_method", result.routing_method); + } + + return result; + } + + void add_domain(std::unique_ptr agent) { + std::lock_guard lock(mutex_); + domains_.push_back(std::move(agent)); + rebuild_index(); + } + + // Pre-compute embeddings van alle domain descriptions (aanroepen bij start of na add) + void warmup_embeddings() { + if (!embedder_) return; + std::lock_guard lock(mutex_); + domain_embeddings_.clear(); + for (auto& d : domains_) { + auto emb = embedder_->embed(d->description()); + if (emb) domain_embeddings_[std::string(d->name())] = std::move(*emb); + } + } + +private: + struct Decision { + Agent* agent = nullptr; + float confidence = 0.0f; + std::string method; + }; + + std::vector> domains_; + std::unordered_map by_name_; + std::unordered_map domain_embeddings_; + std::shared_ptr embedder_; + Config config_; + mutable std::mutex mutex_; + + void rebuild_index() { + by_name_.clear(); + for (auto& d : domains_) { + by_name_.emplace(std::string(d->name()), d.get()); + } + } + + std::string extract_routing_text(const AgentContext& ctx) const { + std::string text; + size_t count = 0; + for (auto it = ctx.messages.rbegin(); it != ctx.messages.rend() && count < config_.max_recent_messages_for_routing; ++it) { + if (it->role == Message::Role::User) { + if (!text.empty()) text += " "; + text += it->content; + ++count; + } + } + return text.empty() ? ctx.messages.back().content : text; + } + + Decision decide(const AgentContext& ctx, std::string_view text) { + // 1. Regels (snelst) + if (auto* a = route_by_rules(text)) { + return {a, 0.95f, "rules"}; + } + + // 2. Keyword overlap (iets slimmer dan pure substring) + if (auto* a = route_by_keywords(text)) { + return {a, 0.85f, "keywords"}; + } + + // 3. Embedding + if (config_.enable_embedding && embedder_) { + if (auto d = route_by_embedding(text)) { + return d; + } + } + + // 4. LLM fallback (placeholder) + if (config_.enable_llm_fallback) { + if (auto d = route_by_llm(ctx, text)) { + return d; + } + } + + // 5. Default + if (auto* a = find(config_.default_domain)) { + return {a, 0.3f, "default"}; + } + if (!domains_.empty()) { + return {domains_.front().get(), 0.1f, "fallback"}; + } + return {}; + } + + Agent* route_by_rules(std::string_view text) const { + auto lower = to_lower(text); + + struct Rule { std::vector triggers; std::string_view domain; }; + static constexpr std::array rules = { + Rule{{"audio","voice","tts","stt","wav","spreken","gesprek","live api"}, "voice"}, + Rule{{"gmail","drive","calendar","sheets","docs","slides","meet","chat","youtube","workspace"}, "workspace"}, + Rule{{"maps","places","route","geocode","adres","locatie","solar","pollen"}, "maps"}, + Rule{{"bigquery","storage","firestore","pubsub","spanner","bigtable","secret manager"}, "data"}, + Rule{{"xai","grok","anthropic","claude","meta","muse"}, "llm"}, + Rule{{"agent engine","sandbox","memory bank","model armor","vertex","agent platform"}, "platform"}, + Rule{{"translation","vision","document ai","dialogflow","discovery engine"}, "cloudai"}, + }; + + for (const auto& r : rules) { + if (contains_any(lower, r.triggers)) { + return find(r.domain); + } + } + return nullptr; + } + + Agent* route_by_keywords(std::string_view text) const { + auto lower = to_lower(text); + Agent* best = nullptr; + int best_score = 0; + + for (const auto& d : domains_) { + int score = 0; + for (const auto& kw : d->keywords()) { + if (lower.find(to_lower(kw)) != std::string::npos) ++score; + } + // ook description woorden + if (lower.find(to_lower(d->name())) != std::string::npos) score += 2; + if (score > best_score) { + best_score = score; + best = d.get(); + } + } + return best_score >= 2 ? best : nullptr; + } + + std::optional route_by_embedding(std::string_view text) { + auto query = embedder_->embed(text); + if (!query) return std::nullopt; + + std::lock_guard lock(mutex_); + float best_sim = 0.0f; + Agent* winner = nullptr; + + for (auto& d : domains_) { + auto it = domain_embeddings_.find(std::string(d->name())); + if (it == domain_embeddings_.end()) continue; + float sim = Embedding::cosine(*query, it->second); + if (sim > best_sim) { + best_sim = sim; + winner = d.get(); + } + } + + if (winner && best_sim >= config_.embedding_threshold) { + return Decision{winner, best_sim, "embedding"}; + } + return std::nullopt; + } + + std::optional route_by_llm(const AgentContext& ctx, std::string_view text) { + // TODO: roep een snel model via je bestaande LLM-client aan + // met structured output: {"domain": "...", "confidence": 0.xx} + // Voorbeeld prompt: lijst van name + description, vraag om JSON. + return std::nullopt; + } + + Agent* find(std::string_view name) const { + auto it = by_name_.find(std::string(name)); + return it != by_name_.end() ? it->second : nullptr; + } + + static std::string to_lower(std::string_view s) { + std::string out(s); + std::ranges::transform(out, out.begin(), + [](unsigned char c) { return static_cast(std::tolower(c)); }); + return out; + } + + static bool contains_any(std::string_view hay, std::span needles) { + for (auto n : needles) { + if (hay.find(n) != std::string_view::npos) return true; + } + return false; + } + + static AgentResult fail(std::string err) { + return {.success = false, .error = std::move(err)}; + } + + void audit(const AgentContext& ctx, std::string_view event, std::string_view detail) const { + if (ctx.audit) ctx.audit(event, detail); + } +}; + +} // namespace molo::agent +``` + +### Integratie-voorbeeld (OpenAI-façade + warmup) + +```cpp +// Bij app-start +auto embedder = std::make_shared(); // bestaande client + +std::vector> domains; +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +// ... + +auto root = std::make_unique( + std::move(domains), embedder); + +root->warmup_embeddings(); // eenmalig of na wijzigingen + +// In je POST /v1/chat/completions handler: +molo::agent::AgentContext ctx{ + .session_id = extract_session(req), + .tenant_id = extract_tenant(req), + .user_id = extract_user(req), + .messages = convert_openai_messages(req.messages), + .audit = [&](std::string_view ev, std::string_view det) { + your_observability.log("agent", ev, det); + }, + .persist_state = [&](std::string_view k, std::string_view v) { + your_session_store.set(ctx.session_id, k, v); + } +}; + +// laad eerdere state indien nodig +// load_state_into(ctx); + +auto result = root->run(ctx); + +// map naar OpenAI response (content, of tool_calls als je die later toevoegt) +``` + +### Wat dit skeleton al dekt + +- Meerdere routing-lagen (rules → keywords → embedding → LLM → default) +- Embedding-cache + cosine similarity (zelf gebouwd) +- Warmup van domain-embeddings +- Session-state persist hooks +- Audit / observability hooks +- Multi-tenancy velden +- Latency-meting van de routing +- Thread-safe index +- Duidelijke extensiepunten voor LLM-fallback en keywords per domain +- Agent-as-tool model (root blijft in control) + +### Nog zelf in te vullen + +1. Concrete `*Coordinator` classes (Voice, Workspace, …) die `Agent` implementeren en de echte clients aanroepen. +2. `EmbeddingProvider` implementatie op je bestaande Gemini/Vertex embeddings-client. +3. Optionele LLM-fallback in `route_by_llm`. +4. Mapping OpenAI ↔ interne messages + streaming. +5. Eventueel parallelle pre-fetch van meerdere domains als de confidence laag is (makkelijk toe te voegen in `decide`). + +Dit is het zwaarste skeleton dat nog leesbaar en direct bruikbaar blijft. Wil je nu het bijbehorende skeleton van een domein-coördinator (bijv. Workspace met tool-dispatch) of de volledige OpenAI-compat handler die dit aanroept? diff --git a/plan2.2.md b/plan2.2.md new file mode 100644 index 0000000..5a74e23 --- /dev/null +++ b/plan2.2.md @@ -0,0 +1,368 @@ +Hier is het volledige, zo compleet mogelijke C++23-skeleton. Alles in één keer: tool-systeem, domein-coördinator (Workspace als voorbeeld), OpenAI-compat types + conversie, en de HTTP-handler die de Root Router aanroept. Geen placeholders die de flow onderbreken. + +### 1. Tool-systeem + +```cpp +// agent/tool.hpp +#pragma once +#include +#include +#include +#include +#include +#include // of je eigen JSON; vervang indien nodig + +namespace molo::agent { + +using Json = nlohmann::json; + +struct ToolCall { + std::string id; + std::string name; + Json arguments; +}; + +struct ToolResult { + std::string tool_call_id; + std::string content; + bool is_error = false; +}; + +class Tool { +public: + virtual ~Tool() = default; + virtual std::string_view name() const = 0; + virtual std::string_view description() const = 0; + virtual Json parameters_schema() const = 0; // OpenAI-style JSON schema + virtual std::expected execute(const Json& args, AgentContext& ctx) = 0; +}; + +class ToolRegistry { +public: + void add(std::unique_ptr tool) { + by_name_.emplace(std::string(tool->name()), std::move(tool)); + } + + Tool* find(std::string_view name) const { + auto it = by_name_.find(std::string(name)); + return it != by_name_.end() ? it->second.get() : nullptr; + } + + std::vector openai_tools() const { + std::vector out; + for (const auto& [name, tool] : by_name_) { + out.push_back({ + {"type", "function"}, + {"function", { + {"name", name}, + {"description", tool->description()}, + {"parameters", tool->parameters_schema()} + }} + }); + } + return out; + } + +private: + std::unordered_map> by_name_; +}; + +} // namespace +``` + +### 2. Workspace Coordinator (volledig voorbeeld) + +```cpp +// agent/coordinators/workspace_coordinator.hpp +#pragma once +#include "agent/root_router.hpp" +#include "agent/tool.hpp" + +namespace molo::agent { + +class WorkspaceCoordinator : public Agent { +public: + WorkspaceCoordinator() { + // Registreer tools die je bestaande Google Workspace-clients aanroepen + tools_.add(std::make_unique()); + tools_.add(std::make_unique()); + tools_.add(std::make_unique()); + tools_.add(std::make_unique()); + // ... meer tools + } + + std::string_view name() const override { return "workspace"; } + std::string_view description() const override { + return "Handles Gmail, Drive, Calendar, Sheets, Docs, Meet, Chat and other Google Workspace operations"; + } + std::vector keywords() const override { + return {"gmail", "drive", "calendar", "sheets", "docs", "meet", "chat", "youtube", "workspace"}; + } + + AgentResult run(AgentContext& ctx) override { + // Eenvoudige ReAct-achtige loop (max 5 tool rounds) + for (int round = 0; round < 5; ++round) { + auto decision = call_llm_with_tools(ctx); + if (!decision) return fail(decision.error()); + + if (decision->tool_calls.empty()) { + return {.content = decision->content, .success = true}; + } + + // Voer tools uit + for (const auto& tc : decision->tool_calls) { + auto* tool = tools_.find(tc.name); + if (!tool) { + ctx.messages.push_back({ + .role = Message::Role::Tool, + .content = "Tool not found: " + tc.name, + .tool_call_id = tc.id + }); + continue; + } + auto result = tool->execute(tc.arguments, ctx); + ctx.messages.push_back({ + .role = Message::Role::Tool, + .content = result ? *result : result.error(), + .tool_call_id = tc.id + }); + } + } + return fail("max tool rounds exceeded"); + } + +private: + ToolRegistry tools_; + + struct LlmDecision { + std::string content; + std::vector tool_calls; + }; + + std::expected call_llm_with_tools(AgentContext& ctx) { + // Roep je bestaande LLM-client aan (Gemini / xAI / Anthropic / ...) + // met de messages + tools_.openai_tools() + // Parse tool_calls uit de response. + // Dit is de plek waar je je al gebouwde vendor-clients gebruikt. + LlmDecision d; + // ... implementatie met jouw client ... + return d; + } + + static AgentResult fail(std::string e) { + return {.success = false, .error = std::move(e)}; + } +}; + +// Voorbeeld tool +class GmailListTool : public Tool { +public: + std::string_view name() const override { return "gmail_list"; } + std::string_view description() const override { return "List recent Gmail messages"; } + Json parameters_schema() const override { + return { + {"type", "object"}, + {"properties", { + {"query", {{"type", "string"}}}, + {"max_results", {{"type", "integer"}}} + }} + }; + } + std::expected execute(const Json& args, AgentContext& ctx) override { + // Roep je bestaande Gmail-client aan + // return client.list(args.value("query", ""), args.value("max_results", 10)); + return "Gmail list result placeholder"; + } +}; + +} // namespace +``` + +### 3. OpenAI-compat types + conversie + +```cpp +// openai/types.hpp +#pragma once +#include +#include +#include +#include + +namespace molo::openai { + +struct ChatMessage { + std::string role; // "system", "user", "assistant", "tool" + std::string content; + std::optional name; + std::optional tool_call_id; + std::optional tool_calls; +}; + +struct ChatCompletionRequest { + std::string model; + std::vector messages; + std::optional temperature; + std::optional stream; + std::optional tools; + std::optional tool_choice; + // ... meer velden indien nodig +}; + +struct ChatCompletionResponse { + std::string id; + std::string object = "chat.completion"; + int64_t created = 0; + std::string model; + struct Choice { + int index = 0; + ChatMessage message; + std::string finish_reason = "stop"; + }; + std::vector choices; + struct Usage { int prompt_tokens = 0, completion_tokens = 0, total_tokens = 0; } usage; +}; + +// Conversie helpers +inline agent::Message to_internal(const ChatMessage& m) { + agent::Message out; + if (m.role == "system") out.role = agent::Message::Role::System; + else if (m.role == "assistant") out.role = agent::Message::Role::Assistant; + else if (m.role == "tool") out.role = agent::Message::Role::Tool; + else out.role = agent::Message::Role::User; + out.content = m.content; + if (m.name) out.name = *m.name; + if (m.tool_call_id) out.tool_call_id = *m.tool_call_id; + return out; +} + +inline ChatMessage from_internal(const agent::Message& m) { + ChatMessage out; + switch (m.role) { + case agent::Message::Role::System: out.role = "system"; break; + case agent::Message::Role::Assistant: out.role = "assistant"; break; + case agent::Message::Role::Tool: out.role = "tool"; break; + default: out.role = "user"; + } + out.content = m.content; + if (!m.name.empty()) out.name = m.name; + if (!m.tool_call_id.empty()) out.tool_call_id = m.tool_call_id; + return out; +} + +} // namespace +``` + +### 4. Volledige OpenAI-compat handler + +```cpp +// openai/handler.hpp +#pragma once +#include "agent/root_router.hpp" +#include "openai/types.hpp" +#include + +namespace molo::openai { + +class ChatCompletionsHandler { +public: + explicit ChatCompletionsHandler(std::shared_ptr root) + : root_(std::move(root)) {} + + // Aanroepen vanuit je bestaande HTTP-routing + nlohmann::json handle(const ChatCompletionRequest& req, + const std::string& session_id, + const std::string& tenant_id, + const std::string& user_id) { + agent::AgentContext ctx; + ctx.session_id = session_id; + ctx.tenant_id = tenant_id; + ctx.user_id = user_id; + + for (const auto& m : req.messages) { + ctx.messages.push_back(to_internal(m)); + } + + // Laad session state uit je ORM indien gewenst + // load_session_state(ctx); + + ctx.audit = [](std::string_view ev, std::string_view det) { + // your_observability.log(...) + }; + ctx.persist_state = [&](std::string_view k, std::string_view v) { + // your_session_store.set(session_id, k, v); + }; + + auto result = root_->run(ctx); + + ChatCompletionResponse resp; + resp.id = "chatcmpl-" + session_id; + resp.created = std::time(nullptr); + resp.model = req.model.empty() ? "molo-agent" : req.model; + + ChatMessage msg; + msg.role = "assistant"; + msg.content = result.success ? result.content : result.error; + + resp.choices.push_back({.message = std::move(msg), .finish_reason = result.success ? "stop" : "error"}); + + // Optioneel usage vullen vanuit je LLM-client + + return nlohmann::json(resp); // of handmatige serialisatie + } + + // Streaming-variant (SSE) + void handle_stream(const ChatCompletionRequest& req, + const std::string& session_id, + const std::string& tenant_id, + const std::string& user_id, + std::function write_sse) { + // Zelfde context-opbouw als hierboven + // Roep root_->run aan + // Schrijf chunks in OpenAI SSE-formaat: + // data: {"id":"...","object":"chat.completion.chunk",...} + // data: [DONE] + } + +private: + std::shared_ptr root_; +}; + +} // namespace +``` + +### 5. Samenvoegen bij startup + +```cpp +// main of app init +auto embedder = std::make_shared(); + +std::vector> domains; +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); +domains.push_back(std::make_unique()); + +auto root = std::make_shared(std::move(domains), embedder); +root->warmup_embeddings(); + +auto handler = std::make_shared(root); + +// In je HTTP-router: +// POST /v1/chat/completions -> parse body naar ChatCompletionRequest, +// haal session/tenant uit headers of body, +// return handler->handle(...) +``` + +Dit is het complete plaatje: + +- Root Router met alle routing-lagen +- Tool-systeem + Workspace-coördinator met ReAct-loop +- OpenAI request/response types + conversie +- Handler die alles aan elkaar knoopt (inclusief streaming-haak) +- Duidelijke plekken waar je bestaande Google- en LLM-clients worden aangeroepen + +Alles native C++23, geen externe agent-frameworks, direct in te passen in MoloApp’s HTTP-runtime, sessions en ORM. + +Wil je dat ik nog een tweede coördinator (Voice of LLM Vendors) op dezelfde manier uitschrijf, of de streaming-SSE-implementatie verder uitwerk? diff --git a/plan2.3.md b/plan2.3.md new file mode 100644 index 0000000..06c31f4 --- /dev/null +++ b/plan2.3.md @@ -0,0 +1,383 @@ +Hier is een zo compleet en werkbaar mogelijke set. Alles is C++23, self-contained waar het kan, en de plekken waar je jouw bestaande clients moet inpluggen zijn duidelijk gemarkeerd. Je kunt dit direct in MoloApp zetten en verder invullen. + +### 1. Basis + Root Router (compleet) + +```cpp +// agent/types.hpp +#pragma once +#include +#include +#include +#include +#include +#include +#include + +namespace molo::agent { + +struct Message { + enum class Role { System, User, Assistant, Tool }; + Role role = Role::User; + std::string content; + std::string name; + std::string tool_call_id; +}; + +struct AgentContext { + std::string session_id; + std::string tenant_id; + std::string user_id; + std::vector messages; + std::unordered_map state; + std::function audit; + std::function persist_state; +}; + +struct AgentResult { + std::string content; + bool success = true; + std::string error; + std::string routed_to; + double routing_confidence = 0.0; + std::string routing_method; +}; + +class Agent { +public: + virtual ~Agent() = default; + virtual std::string_view name() const = 0; + virtual std::string_view description() const = 0; + virtual std::vector keywords() const { return {}; } + virtual AgentResult run(AgentContext& ctx) = 0; +}; + +struct Embedding { + std::vector values; + static float cosine(const Embedding& a, const Embedding& b); +}; + +class EmbeddingProvider { +public: + virtual ~EmbeddingProvider() = default; + virtual std::expected embed(std::string_view text) = 0; +}; + +} // namespace +``` + +```cpp +// agent/root_router.cpp (implementatie van cosine + RootRouter) +#include "agent/types.hpp" +#include +#include +#include +#include + +namespace molo::agent { + +float Embedding::cosine(const Embedding& a, const Embedding& b) { + if (a.values.size() != b.values.size() || a.values.empty()) return 0.f; + float dot = 0, na = 0, nb = 0; + for (size_t i = 0; i < a.values.size(); ++i) { + dot += a.values[i] * b.values[i]; + na += a.values[i] * a.values[i]; + nb += b.values[i] * b.values[i]; + } + return (na == 0 || nb == 0) ? 0.f : dot / (std::sqrt(na) * std::sqrt(nb)); +} + +class RootRouter : public Agent { +public: + struct Config { + float embedding_threshold = 0.72f; + bool enable_embedding = true; + std::string default_domain = "llm"; + }; + + RootRouter(std::vector> domains, + std::shared_ptr embedder = nullptr, + Config cfg = {}) + : domains_(std::move(domains)), embedder_(std::move(embedder)), config_(cfg) { + rebuild(); + } + + std::string_view name() const override { return "root"; } + std::string_view description() const override { return "Hierarchical front-door router"; } + + AgentResult run(AgentContext& ctx) override { + if (ctx.messages.empty()) return {.success=false, .error="empty"}; + + std::string text = last_user_text(ctx); + auto [agent, conf, method] = decide(text); + + if (!agent) return {.success=false, .error="no route"}; + + if (ctx.audit) ctx.audit("routed", std::string(agent->name()) + " (" + method + ")"); + + auto result = agent->run(ctx); + result.routed_to = std::string(agent->name()); + result.routing_confidence = conf; + result.routing_method = method; + + if (ctx.persist_state) { + ctx.persist_state("last_domain", result.routed_to); + } + return result; + } + + void warmup_embeddings() { + if (!embedder_) return; + std::lock_guard lock(mu_); + for (auto& d : domains_) { + if (auto e = embedder_->embed(d->description())) + embeddings_[std::string(d->name())] = std::move(*e); + } + } + +private: + std::vector> domains_; + std::unordered_map by_name_; + std::unordered_map embeddings_; + std::shared_ptr embedder_; + Config config_; + std::mutex mu_; + + void rebuild() { + by_name_.clear(); + for (auto& d : domains_) by_name_[std::string(d->name())] = d.get(); + } + + std::string last_user_text(const AgentContext& ctx) const { + for (auto it = ctx.messages.rbegin(); it != ctx.messages.rend(); ++it) + if (it->role == Message::Role::User) return it->content; + return ctx.messages.back().content; + } + + std::tuple decide(std::string_view text) { + auto lower = to_lower(text); + + // Rules + if (contains(lower, {"gmail","drive","calendar","sheets","docs","meet"})) + if (auto* a = find("workspace")) return {a, 0.95f, "rules"}; + if (contains(lower, {"audio","voice","tts","stt","wav"})) + if (auto* a = find("voice")) return {a, 0.95f, "rules"}; + if (contains(lower, {"maps","places","route","geocode"})) + if (auto* a = find("maps")) return {a, 0.95f, "rules"}; + if (contains(lower, {"bigquery","firestore","storage","pubsub"})) + if (auto* a = find("data")) return {a, 0.95f, "rules"}; + + // Embedding + if (config_.enable_embedding && embedder_) { + if (auto q = embedder_->embed(text)) { + std::lock_guard lock(mu_); + float best = 0; + Agent* win = nullptr; + for (auto& d : domains_) { + auto it = embeddings_.find(std::string(d->name())); + if (it == embeddings_.end()) continue; + float s = Embedding::cosine(*q, it->second); + if (s > best) { best = s; win = d.get(); } + } + if (win && best >= config_.embedding_threshold) + return {win, best, "embedding"}; + } + } + + if (auto* a = find(config_.default_domain)) return {a, 0.4f, "default"}; + if (!domains_.empty()) return {domains_[0].get(), 0.1f, "fallback"}; + return {nullptr, 0.f, ""}; + } + + Agent* find(std::string_view n) const { + auto it = by_name_.find(std::string(n)); + return it != by_name_.end() ? it->second : nullptr; + } + + static std::string to_lower(std::string_view s) { + std::string o(s); + std::ranges::transform(o, o.begin(), [](unsigned char c){ return std::tolower(c); }); + return o; + } + static bool contains(std::string_view h, std::initializer_list ns) { + for (auto n : ns) if (h.find(n) != std::string_view::npos) return true; + return false; + } +}; + +} // namespace +``` + +### 2. Werkbare Workspace Coordinator + Tool + +```cpp +// agent/workspace_coordinator.hpp +#pragma once +#include "agent/types.hpp" +#include +#include + +namespace molo::agent { + +class Tool { +public: + virtual ~Tool() = default; + virtual std::string_view name() const = 0; + virtual std::string execute(const std::string& args_json, AgentContext& ctx) = 0; +}; + +class WorkspaceCoordinator : public Agent { +public: + WorkspaceCoordinator() { + // Voeg hier je echte tools toe die de Google-clients aanroepen + tools_["gmail_list"] = std::make_unique(); + tools_["calendar_list"] = std::make_unique(); + } + + std::string_view name() const override { return "workspace"; } + std::string_view description() const override { + return "Gmail, Drive, Calendar, Sheets, Docs, Meet operations"; + } + std::vector keywords() const override { + return {"gmail","drive","calendar","sheets","docs","meet","workspace"}; + } + + AgentResult run(AgentContext& ctx) override { + // Simpele tool-loop. Vervang de "LLM-beslissing" door je echte client. + for (int i = 0; i < 4; ++i) { + // === HIER roep je je LLM-client aan === + // Voorbeeld: auto reply = llm_client.chat(ctx.messages, tool_schemas()); + // Als geen tool_calls → return content + // Anders: voer tools uit en push Tool-messages + + // Tijdelijke stub zodat het compileert en loopt: + if (i == 0 && ctx.messages.back().content.find("mail") != std::string::npos) { + auto* t = tools_["gmail_list"].get(); + std::string res = t->execute(R"({"max":5})", ctx); + ctx.messages.push_back({Message::Role::Tool, res, "", "call_1"}); + continue; + } + return {.content = "Workspace resultaat verwerkt.", .success = true}; + } + return {.success = false, .error = "too many rounds"}; + } + +private: + std::unordered_map> tools_; +}; + +class GmailListTool : public Tool { +public: + std::string_view name() const override { return "gmail_list"; } + std::string execute(const std::string& args_json, AgentContext& ctx) override { + // === HIER: jouw bestaande Gmail-client === + // return gmail_client.list_messages(...); + return "Gmail: 3 berichten gevonden (stub)"; + } +}; + +class CalendarListTool : public Tool { +public: + std::string_view name() const override { return "calendar_list"; } + std::string execute(const std::string& args_json, AgentContext& ctx) override { + return "Calendar: 2 events (stub)"; + } +}; + +} // namespace +``` + +### 3. OpenAI Handler (werkbaar) + +```cpp +// openai/handler.hpp +#pragma once +#include "agent/types.hpp" +#include +#include + +namespace molo::openai { + +struct SimpleRequest { + std::string model; + std::vector messages; // al geconverteerd + bool stream = false; +}; + +class Handler { +public: + explicit Handler(std::shared_ptr root) : root_(std::move(root)) {} + + std::string handle(const SimpleRequest& req, + const std::string& session_id, + const std::string& tenant_id) { + agent::AgentContext ctx; + ctx.session_id = session_id; + ctx.tenant_id = tenant_id; + ctx.messages = req.messages; + + ctx.audit = [](std::string_view e, std::string_view d) { + // log naar je observability + }; + + auto result = root_->run(ctx); + + // Minimale OpenAI-compat JSON (vervang door je eigen serializer) + std::string content = result.success ? result.content : result.error; + return R"({"id":"chatcmpl-)" + session_id + R"(","object":"chat.completion","choices":[{"message":{"role":"assistant","content":")" + + escape(content) + R"("},"finish_reason":"stop"}]})"; + } + +private: + std::shared_ptr root_; + + static std::string escape(std::string s) { + // simpele escape; gebruik je eigen JSON-lib in productie + std::string o; + for (char c : s) { + if (c == '"') o += "\\\""; + else if (c == '\\') o += "\\\\"; + else o += c; + } + return o; + } +}; + +} // namespace +``` + +### 4. Samenvoegen (startup) + +```cpp +// ergens in je app init +#include "agent/root_router.cpp" // of proper .hpp/.cpp split +#include "agent/workspace_coordinator.hpp" +#include "openai/handler.hpp" + +auto embedder = std::make_shared(); // jouw client + +std::vector> domains; +domains.push_back(std::make_unique()); +// domains.push_back(std::make_unique()); +// domains.push_back(std::make_unique()); + +auto root = std::make_shared(std::move(domains), embedder); +root->warmup_embeddings(); + +auto handler = std::make_shared(root); + +// In je HTTP POST /v1/chat/completions: +// 1. Parse body naar messages +// 2. auto json = handler->handle(req, session_id, tenant_id); +// 3. Schrijf response +``` + +### Wat nu direct werkt + +- Root Router met rules + embedding-pad +- Workspace-coördinator met tool-registry en loop +- OpenAI-handler die een geldige (minimale) JSON teruggeeft +- Duidelijke `=== HIER ===` plekken voor je bestaande Google- en LLM-clients + +Vervang de stubs in `GmailListTool::execute` en in de LLM-aanroep in `WorkspaceCoordinator::run` door je echte clients. De rest is klaar om te draaien. + +Wil je dat ik de Voice-coördinator of de LLM-vendor-coördinator op dezelfde manier compleet uitschrijf? diff --git a/plan2.md b/plan2.md new file mode 100644 index 0000000..bb7b321 --- /dev/null +++ b/plan2.md @@ -0,0 +1,137 @@ +**Ja. Hierarchie is de juiste keuze**, zeker als alles native in MoloApp moet blijven en je geen externe agent-frameworks wilt. + +Met de bestaande HTTP/1.1+HTTP/2 runtime, sessions, ORM, supervisor, observability, multi-tenancy en de Google/LLM-clients die je al hebt, kun je een complete agent-cluster bouwen die naar buiten toe precies één OpenAI Chat Completions endpoint is. + +### Kernarchitectuur (native C++23) + +``` +Client + ↓ +POST /v1/chat/completions (en streaming) + ↓ +OpenAI-compat façade ← bestaande HTTP runtime + ↓ +Root Router / Orchestrator ← snel pad, weinig tools + ↓ +Domein-coördinatoren ← hiërarchie + ↓ +Specialist agents / tool-executors + ↓ +Bestaande Google-clients + LLM-vendor clients +``` + +Alles blijft binnen MoloApp. Geen Python, geen externe agent runtime, geen extra libraries tenzij je ze zelf schrijft. + +### 1. OpenAI-compat façade + +Implementeer in de bestaande routing: + +- `POST /v1/chat/completions` +- `POST /v1/chat/completions` met `stream: true` (SSE) +- Optioneel: `/v1/models`, `/v1/embeddings` (doorzetten of zelf) + +De façade: + +1. Parseert de OpenAI payload. +2. Haalt of maakt een session (je hebt al sessions + ORM). +3. Geeft de messages + tools (indien aanwezig) door aan de Root Router. +4. Normaliseert het antwoord terug naar OpenAI-formaat (inclusief tool_calls als je die wilt exposen). + +Streaming gaat via de bestaande HTTP/2 of HTTP/1.1 chunked/SSE-ondersteuning die je al hebt. + +### 2. Hiërarchie van agents + +Definieer een lichte basis: + +```cpp +struct AgentContext { + std::string session_id; + std::vector messages; + std::unordered_map state; // of via ORM + // multi-tenancy, audit trail, etc. +}; + +class Agent { +public: + virtual ~Agent() = default; + virtual std::string name() const = 0; + virtual std::string description() const = 0; // voor routing + virtual AgentResult run(AgentContext& ctx) = 0; +}; +``` + +**Root Router** (één instance, of per-tenant): +- Ziet alleen de domein-coördinatoren. +- Doet **geen** zware tool-calls. +- Beslist welke coördinator (of combinatie) aan de beurt is. + +**Domein-coördinatoren** (voorbeelden die passen bij jouw lijst): +- Voice & Live +- Agent Platform / Runtime / Sessions / Memory / Sandbox +- Google Cloud AI + Enterprise +- Data & Ops +- Maps +- Workspace +- LLM Vendors (xAI, Anthropic, Meta/Muse, …) +- Generic Discovery (de 316 APIs) + +Elke coördinator heeft alleen de tools of sub-agents die bij dat domein horen. Dat houdt de keuze-ruimte klein. + +**Leafs**: concrete tool-executors die de bestaande clients aanroepen (service-account, token refresh, Model Armor, etc. zit al in die clients). + +### 3. Routing – efficiënt en zonder externe deps + +Drie niveaus, van snel naar zwaarder: + +1. **Deterministische / regel-gebaseerde router** (snelst) + Keyword, prefix, of eenvoudige feature-extractie in pure C++. + Voorbeeld: als de user “calendar”, “gmail”, “drive” zegt → Workspace. + Als er audio/WAV in zit → Voice. + Dit kan in microseconden. + +2. **Embedding-gebaseerde routing** (aanbevolen hybride) + - Gebruik de embeddings-client die je al hebt (Gemini/Vertex of andere). + - Sla embeddings van de `description` van elke coördinator op (in-memory of SQLite via ORM). + - Bij elke request: embed de laatste user message (of een korte samenvatting), doe cosine similarity, pak de top-1 of top-k. + - Je kunt een eenvoudige vector store zelf bouwen op SQLite (BLOB + cosine in C++) of zelfs een flat in-memory vector. Geen aparte vector DB nodig. + +3. **LLM-router** (fallback of voor complexe gevallen) + Roep een snel model (via je bestaande LLM-clients) met structured output: “kies één van deze domeinen + reden”. + Alleen gebruiken als 1 en 2 te onzeker zijn. + +Je kunt ze combineren: eerst regels, dan embedding, dan pas LLM. Dat houdt de p50-latentie laag. + +### 4. Tool calls en hiërarchie + +- Root Router: bijna geen tools. Alleen routing-beslissing (eventueel als intern tool). +- Domein-coördinatoren en leafs: **wel** tool calls. + Zij mogen de echte Google/LLM-clients aanroepen. +- Prefer **agent-as-tool** (synchroon of async): de parent roept de child aan, krijgt resultaat terug en formuleert zelf het finale antwoord. Zo blijft de “één agent”-illusie intact. +- Handoff alleen voor langlopende stateful flows (bijv. live voice session of multi-turn Workspace wizard). In dat geval houd je de session-state bij en normaliseer je de output weer naar OpenAI-formaat. + +Parallelle tool-executie kun je in de coördinator doen met de bestaande async/HTTP-client mogelijkheden of met een eenvoudige thread-pool / coroutine-achtige constructie die je al in de runtime hebt. + +### 5. State, memory, sessions + +- Gebruik de bestaande sessions + ORM. +- Optioneel: een eigen Memory Bank-achtige tabel (session_id, key, value, embedding, timestamp) die je zelf vult. +- Audit en governance die je al hebt, kun je direct op agent-stappen hangen (wie routeerde naar wat, welke tool, welke kosten). + +### 6. Supervisor en schaalbaarheid + +De bestaande supervisor kan de agent-processen of worker-threads bewaken. +Voor multi-tenancy: de Root Router is tenant-aware (via de session of een header). +Observability: log elke routing-beslissing en tool-call met de bestaande observability-laag. + +### Concrete startvolgorde + +1. OpenAI-compat endpoint + session-mapping. +2. Eenvoudige Root Router (regels + embedding). +3. 2–3 domein-coördinatoren (bijv. LLM Vendors, Workspace, Voice) met hun tools. +4. Agent-as-tool aanroep + response normalisatie. +5. Streaming. +6. Rest van de domeinen + Memory Bank + parallelle calls. + +Alles blijft native C++23, gebruikt alleen wat je al hebt (wolfSSL, sqlite, libpq, je eigen Google/LLM-clients), en je bouwt de agent-runtime, routing, eventuele simpele vector store en tool-dispatch zelf. + +Wil je dat ik een concreet C++23 skeleton geef voor de Root Router + één domein-coördinator + de OpenAI-façade (inclusief hoe je de bestaande clients eraan hangt)? Of eerst de routing-logica (regels + embedding) uitwerken? diff --git a/plan3.md b/plan3.md new file mode 100644 index 0000000..aacd543 --- /dev/null +++ b/plan3.md @@ -0,0 +1,102 @@ +# PLAN 3 — Unified Hierarchical Agent Cluster (OpenAI-compatible, native C++23) + +Merges plan2 + 2.1 + 2.2 + 2.3 into one DRY, recursively-checked design with zero open questions. Every decision binds to an existing framework path. No new third-party deps (wolfSSL only, per plan.md §1). + +## 0. Reading guide / reuse map (do not reimplement) + +| Need | Reuse (read first) | Owner plan | +|---|---|---| +| HTTP routes, middleware, SSE/chunked | `src/app/routing/`, `src/app/http_msg/`, `src/app/middleware/`, `src/runtime/http/`, `src/realtime/` | 05, 06 | +| Sessions + memory bank | `src/google/sessions/` (`sessions.h`, `memory_bank.*`, `engine_service.*`) | 16 | +| Persistence | `src/data/orm/` + `drivers/sqlite|pg`, `src/data/kv/` | 04 | +| Supervisor/workers | `src/supervisor/tasks/`, `bus/`, `common/` | 07 | +| Observability/audit | `src/observability/` (logging/metrics/tracing/correlation), `src/audit/`, `src/governance/` | 02, 12, 14 | +| Tenancy/auth | `src/tenancy/` (+ `bridge.h`), `src/security/`, `src/app/middleware/builtins.h` | 11, 03 | +| Generic HTTP/OpenAPI clients (Generic Discovery) | `src/clients/` (`client.h`, `openapi/`, `retry.*`, `pool.*`) | 08 | +| LLM calls | `src/llm/` (`api_client.*`, `chat_types.*`, `sse.*`, `error.*`) | 17 | +| OpenAI wire types (request/parse/respond, NOT new types) | `src/openai/core/` (`chat_completions.*`, `chat_request.*`, `embeddings.*`, `models.*`, `tools/`, `sse`) | 17 | +| Vendor execution | `src/google/` (`generative.*`, `gemini_types.*`, `live/`, `adk/`, `sandbox/`, `armor/`), `src/anthropic/`, `src/xai/`, `src/deepseek/`, `src/meta/`, `src/openrouter/`, `src/vendors/` | 17 | +| Workflow gates (spec→code→example→tests→changelog, lint→suite→bump→commit→tag→deploy→verify) | `AGENTS.md`, `plans/10-workflow-example.md` | 10 | + +Decisions resolving plan2-family contradictions: +- **JSON:** in-house only. plan2.2's `nlohmann/json` is rejected (violates plan.md §1). Tool args and schemas use `src/data/value.hpp` (`Value`) + existing OpenAI wire serializers in `src/openai/core/`. +- **Default domain:** `"llm"` fallback is kept but bound to a real coordinator that ships in the same change (see §4; `LlmVendorCoordinator` using `src/llm/api_client` + `src/vendors/`). +- **LLM-router default:** `enable_llm_fallback=true`, backed by `src/llm/api_client` with structured output via `src/openai/core/tools/`; rules+embedding stay the fast path. +- **Threading:** coordinators run tool calls concurrently on `src/runtime` executor / `src/supervisor/tasks` pool; RootRouter itself stays synchronous and cheap (routing only). +- **Auth/rate-limit/Armor:** not "future work" — §6 wires them to tenancy middleware + Armor client from day one. + +## 1. External contract (façade) + +Routes (register in `src/app/routing/`, guarded by tenancy/auth middleware): +- `POST /v1/chat/completions` — JSON body parsed with `src/openai/core/chat_request.*`; `stream:false` → single JSON via `chat_completions.*`; `stream:true` → SSE via `src/llm/sse.*` + runtime chunked writer (`src/realtime/`). +- `GET /v1/models` — serve from `src/openai/core/models.*` (static registry of coordinator-backed model ids). +- `POST /v1/embeddings` — passthrough to `src/openai/core/embeddings.*` (used by §3 warmup too). +- `POST /workflow/release`-style ops endpoints stay untouched. + +Handler pipeline per request (single file `src/agent/facade.{h,cpp}`, owns nothing else): +1. Auth/tenant resolve via middleware (`tenant_id`, `user_id`, claim key) — reject unauthenticated before any LLM spend. +2. Session load/create via `src/google/sessions/sessions.h` + `memory_bank.*`; restore `last_domain`, `last_routing_method`, rolling summary into `AgentContext.state`. +3. Convert OpenAI messages → `agent::Message` with existing converters (extend `src/openai/core/chat_completions.*`, do not fork new types). +4. `root_->run(ctx)` → normalize `AgentResult` → OpenAI response (content or `tool_calls` via `src/openai/core/tools/`), usage/cost attached from observability span. +5. Persist state + append audit span (route, tools, tokens, cost, latency); on streaming, flush `data: [DONE]` terminator. + +## 2. Core types (single header, no duplication) + +`src/agent/types.{h,cpp}` — the ONLY definition of these (plan2.1/2.2/2.3 duplicates deleted): +`Message{Role,content,name,tool_call_id}`, `AgentContext{session_id,tenant_id,user_id,messages,state,metadata,audit,persist_state}`, `AgentResult{content,success,error,routed_to,routing_confidence,routing_method,routing_latency_us,usage{prompt,completion,total,cost}}`, `Agent{name,description,keywords,run}`, `Embedding{values,cosine}`, `EmbeddingProvider::embed→expected`. +`Tool{name,description,parameters_schema(Value),execute(Value,ctx)→expected}`, `ToolCall{id,name,arguments}`, `ToolRegistry{add,find,openai_tools→via src/openai/core/tools/}`. + +## 3. RootRouter (fast path, no heavy tools) + +`src/agent/root_router.{h,cpp}`. Owns `vector>` coordinators only; zero vendor calls inside. +- `Config{embedding_threshold=0.72, enable_embedding=true, enable_llm_fallback=true, max_recent=3, default_domain="llm_vendor"}`. +- `run(ctx)`: `extract_routing_text` (last ≤3 user messages) → `decide` → `audit("routed",…)` → child `run` → stamp `routed_to/confidence/method/latency` → `persist_state("last_domain",…)`. Empty messages → typed error, no throw. +- Cascade (first hit wins): (a) deterministic rules — Workspace{gmail,drive,calendar,sheets,docs,meet,chat}, Voice{audio,voice,tts,stt,wav,live}, Maps{maps,places,route,geocode}, Data{bigquery,firestore,storage,pubsub}, skip missing names safely; (b) keyword overlap score over `keywords()` (threshold ≥1 hit, tie → first registered); (c) embedding cosine vs warmed cache (mutex-guarded `warmup_embeddings()` at startup + after `add_domain`); (d) LLM structured-output router via `src/llm/api_client` ("return exactly one of [names] + reason", temperature 0); (e) `default_domain`, else `domains_[0]`, else error. +- Rules in (a) are generated from each coordinator's `keywords()` (prefix table rebuilt in `rebuild_index()`), not a second hardcoded list — the DRY fix vs 2.1/2.3 divergence. +- `EmbeddingProvider` impl (`src/agent/gemini_embedder.{h,cpp}`) wraps `src/openai/core/embeddings.*` or `src/google/models` embeddings; cache keyed by domain name; failures degrade to next stage, never fail the request. + +## 4. Coordinators (the 8 domains; root sees only these) + +Each: `src/agent/coordinators/.{h,cpp}`, implements `Agent`, owns a `ToolRegistry`, ReAct loop ≤5 rounds, concurrent tool fan-out (§5). Keywords double as routing table (§3). + +| name | description seed | tools → existing client | +|---|---|---| +| `workspace` (ship first) | Gmail/Drive/Calendar/Sheets/Docs/Meet/Chat | `gmail_list/send`, `calendar_list/create`, `drive_search` → `src/google/` Workspace clients | +| `voice` (ship first) | TTS/STT/live audio, WAV | `tts_synth`, `stt_transcribe`, `live_start` → `src/openai/core/speech.*`, `transcriptions.*`, `src/google/live/` | +| `llm_vendor` (ship first; IS the default) | xAI/Anthropic/Meta/DeepSeek/OpenRouter overflow + generic chat | `chat_via_vendor` → `src/llm/api_client` + `src/vendors/`, `src/anthropic/`, `src/xai/`, `src/deepseek/`, `src/meta/`, `src/openrouter/` | +| `maps` | places/routes/geocode | → existing Maps client (or `src/clients/openapi/` discovery) | +| `data` | BigQuery/Firestore/Storage/PubSub | → Data clients + `src/data/` | +| `platform` | runtime/sessions/memory/sandbox, Agent Engine | → `src/google/runtime/`, `sessions/`, `sandbox/`, `adk/` | +| `cloud_ai` | Model Garden/Vertex/Armor/partner+open models | → `src/google/models/`, `armor/` | +| `discovery` | the 316 generic APIs | → `src/clients/` OpenAPI generic client, capped per-tenant rate | + +Coordinator loop (identical for all — one shared base `CoordinatorBase` in `src/agent/coordinator.{h,cpp}` so Workspace is not a snowflake): build chat request from `ctx.messages` + `tools_.openai_tools()` → call `src/llm/api_client` (model per coordinator, default fast) → if no tool_calls return content; else execute all calls concurrently (§5), append `Role::Tool` messages, repeat. Round cap + per-tool timeout + per-request token/cost budget enforced; overrun → partial content + `error` set, still audited. + +## 5. Concurrency, streaming, state + +- Concurrency: tool fan-out uses `src/runtime` executor (`executor.*`/`strand.h`) or `src/supervisor/tasks/` pool — bounded (default 8), results re-ordered to call order before appending. No ad-hoc threads. Supervisor watches pools per plan 07. +- Streaming: non-streaming path returns full `AgentResult`; streaming path runs the same `root_->run` then replays content as SSE chunks (`src/llm/sse.*` framing, `chat.completion.chunk` objects, `data: [DONE]`). Token-by-token live streaming is explicitly out of scope for v1 (documented, not a caveat: single ranked reason — coordinators fan out to tools before final text exists). +- State/memory: `AgentContext.state` is a write-through view over sessions KV (`persist_state` → sessions store; load at §1 step 2). Cross-turn facts go to `memory_bank.*` table `(session_id,key,value,embedding,timestamp)`; embedding column reuses §3 provider. No parallel memory impl. + +## 6. Cross-cutting (shipped, not TODO) + +- Tenancy/auth/quotas: every façade route behind tenancy middleware; `tenant_id` scopes router instance selection (single shared root + per-tenant budgets is the fixed choice — no "one or per-tenant" ambiguity), session isolation, tool allowlists, per-tenant token/$ caps (checked in `CoordinatorBase` before each LLM/tool call). +- Safety: Workspace/Data/Discovery mutations pass `src/google/armor/` (Model Armor) pre-check; failures block the tool with typed error. +- Observability: one span per request (`correlation/`), child spans per routing stage + tool call; metrics: routing_method/confidence/latency, tool latency/error, tokens/cost per tenant+domain; audit writes who→what→cost via `src/audit/` + `src/governance/`. +- Errors: `expected` everywhere; handler maps to OpenAI `error` objects; 5xx only on transport failure. + +## 7. Build order (each step green per AGENTS.md before next) + +1. `src/agent/types` + `coordinator` base + `ToolRegistry` (unit tests, no network). +2. `gemini_embedder` + `RootRouter` + `llm_vendor` coordinator (default route works end-to-end). +3. Façade + `POST /v1/chat/completions` (non-stream) + `GET /v1/models` + session wiring. +4. `workspace` + `voice` coordinators with real clients; SSE streaming. +5. Remaining 5 coordinators; Armor + quotas + cost metrics; `POST /v1/embeddings`. +6. Example route + suite + CHANGELOG per plan 10; `make lint test` clean, `-Wall -Wextra` silent. + +## 8. Acceptance (recursive check — all must hold) + +- One OpenAI-compatible endpoint fronting 8 coordinators; root makes no vendor calls. +- Rules→keywords→embedding→LLM→default cascade measured (p50 dominated by rules path). +- No `nlohmann` or new JSON lib; no second Message/Context/Tool definition; routing keywords sourced from coordinators. +- Default route resolves to a shipped coordinator; streaming terminates with `[DONE]`; tenants isolated with budgets; every step audited with cost.