This commit is contained in:
2026-10-26 01:31:48 +01:00
parent 144c95c166
commit 9c4a4ac7e4
5 changed files with 1409 additions and 0 deletions
+419
View File
@@ -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 <string>
#include <string_view>
#include <vector>
#include <memory>
#include <unordered_map>
#include <map>
#include <optional>
#include <functional>
#include <algorithm>
#include <cctype>
#include <cmath>
#include <chrono>
#include <mutex>
#include <span>
#include <array>
#include <expected> // 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<Message> messages;
std::unordered_map<std::string, std::string> state; // session state
std::unordered_map<std::string, std::string> metadata;
// hooks (optioneel invullen vanuit je ORM/session/audit)
std::function<void(std::string_view event, std::string_view detail)> audit;
std::function<void(std::string_view key, std::string_view value)> 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<std::string> keywords() const { return {}; } // optioneel
virtual AgentResult run(AgentContext& ctx) = 0;
};
// ---------------------------------------------------------------------------
// Embedding interface (implementeer met je bestaande client)
// ---------------------------------------------------------------------------
struct Embedding {
std::vector<float> 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<Embedding, std::string> 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<std::unique_ptr<Agent>> domains,
std::shared_ptr<EmbeddingProvider> 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::microseconds>(
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> 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<std::unique_ptr<Agent>> domains_;
std::unordered_map<std::string, Agent*> by_name_;
std::unordered_map<std::string, Embedding> domain_embeddings_;
std::shared_ptr<EmbeddingProvider> 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<std::string_view> 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<Decision> 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<Decision> 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<char>(std::tolower(c)); });
return out;
}
static bool contains_any(std::string_view hay, std::span<const std::string_view> 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<YourGeminiEmbeddingProvider>(); // bestaande client
std::vector<std::unique_ptr<molo::agent::Agent>> domains;
domains.push_back(std::make_unique<VoiceCoordinator>());
domains.push_back(std::make_unique<WorkspaceCoordinator>());
domains.push_back(std::make_unique<MapsCoordinator>());
domains.push_back(std::make_unique<DataCoordinator>());
domains.push_back(std::make_unique<LlmVendorCoordinator>());
domains.push_back(std::make_unique<PlatformCoordinator>());
// ...
auto root = std::make_unique<molo::agent::RootRouter>(
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?
+368
View File
@@ -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 <string>
#include <string_view>
#include <unordered_map>
#include <functional>
#include <expected>
#include <nlohmann/json.hpp> // 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<std::string, std::string> execute(const Json& args, AgentContext& ctx) = 0;
};
class ToolRegistry {
public:
void add(std::unique_ptr<Tool> 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<Json> openai_tools() const {
std::vector<Json> 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<std::string, std::unique_ptr<Tool>> 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<GmailListTool>());
tools_.add(std::make_unique<GmailSendTool>());
tools_.add(std::make_unique<CalendarListTool>());
tools_.add(std::make_unique<DriveSearchTool>());
// ... 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<std::string> 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<ToolCall> tool_calls;
};
std::expected<LlmDecision, std::string> 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<std::string, std::string> 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 <string>
#include <vector>
#include <optional>
#include <nlohmann/json.hpp>
namespace molo::openai {
struct ChatMessage {
std::string role; // "system", "user", "assistant", "tool"
std::string content;
std::optional<std::string> name;
std::optional<std::string> tool_call_id;
std::optional<nlohmann::json> tool_calls;
};
struct ChatCompletionRequest {
std::string model;
std::vector<ChatMessage> messages;
std::optional<float> temperature;
std::optional<bool> stream;
std::optional<nlohmann::json> tools;
std::optional<std::string> 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<Choice> 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 <memory>
namespace molo::openai {
class ChatCompletionsHandler {
public:
explicit ChatCompletionsHandler(std::shared_ptr<agent::RootRouter> 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<void(std::string_view chunk)> 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<agent::RootRouter> root_;
};
} // namespace
```
### 5. Samenvoegen bij startup
```cpp
// main of app init
auto embedder = std::make_shared<YourEmbeddingProvider>();
std::vector<std::unique_ptr<agent::Agent>> domains;
domains.push_back(std::make_unique<agent::WorkspaceCoordinator>());
domains.push_back(std::make_unique<agent::VoiceCoordinator>());
domains.push_back(std::make_unique<agent::MapsCoordinator>());
domains.push_back(std::make_unique<agent::DataCoordinator>());
domains.push_back(std::make_unique<agent::LlmVendorCoordinator>());
domains.push_back(std::make_unique<agent::PlatformCoordinator>());
auto root = std::make_shared<agent::RootRouter>(std::move(domains), embedder);
root->warmup_embeddings();
auto handler = std::make_shared<openai::ChatCompletionsHandler>(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?
+383
View File
@@ -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 <string>
#include <vector>
#include <unordered_map>
#include <functional>
#include <chrono>
#include <optional>
#include <expected>
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<Message> messages;
std::unordered_map<std::string, std::string> state;
std::function<void(std::string_view, std::string_view)> audit;
std::function<void(std::string_view, std::string_view)> 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<std::string> keywords() const { return {}; }
virtual AgentResult run(AgentContext& ctx) = 0;
};
struct Embedding {
std::vector<float> values;
static float cosine(const Embedding& a, const Embedding& b);
};
class EmbeddingProvider {
public:
virtual ~EmbeddingProvider() = default;
virtual std::expected<Embedding, std::string> embed(std::string_view text) = 0;
};
} // namespace
```
```cpp
// agent/root_router.cpp (implementatie van cosine + RootRouter)
#include "agent/types.hpp"
#include <algorithm>
#include <cmath>
#include <mutex>
#include <cctype>
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<std::unique_ptr<Agent>> domains,
std::shared_ptr<EmbeddingProvider> 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<std::unique_ptr<Agent>> domains_;
std::unordered_map<std::string, Agent*> by_name_;
std::unordered_map<std::string, Embedding> embeddings_;
std::shared_ptr<EmbeddingProvider> 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<Agent*, float, std::string> 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<std::string_view> 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 <unordered_map>
#include <memory>
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<GmailListTool>();
tools_["calendar_list"] = std::make_unique<CalendarListTool>();
}
std::string_view name() const override { return "workspace"; }
std::string_view description() const override {
return "Gmail, Drive, Calendar, Sheets, Docs, Meet operations";
}
std::vector<std::string> 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<std::string, std::unique_ptr<Tool>> 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 <memory>
#include <string>
namespace molo::openai {
struct SimpleRequest {
std::string model;
std::vector<agent::Message> messages; // al geconverteerd
bool stream = false;
};
class Handler {
public:
explicit Handler(std::shared_ptr<agent::RootRouter> 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<agent::RootRouter> 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<YourRealEmbeddingProvider>(); // jouw client
std::vector<std::unique_ptr<agent::Agent>> domains;
domains.push_back(std::make_unique<agent::WorkspaceCoordinator>());
// domains.push_back(std::make_unique<VoiceCoordinator>());
// domains.push_back(std::make_unique<LlmCoordinator>());
auto root = std::make_shared<agent::RootRouter>(std::move(domains), embedder);
root->warmup_embeddings();
auto handler = std::make_shared<openai::Handler>(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?
+137
View File
@@ -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<Message> messages;
std::unordered_map<std::string, std::string> 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?
+102
View File
@@ -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<Embedding,string>`.
`Tool{name,description,parameters_schema(Value),execute(Value,ctx)→expected<Value,string>}`, `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<unique_ptr<Agent>>` 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/<name>.{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<T,string>` 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.