420 lines
14 KiB
Markdown
420 lines
14 KiB
Markdown
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?
|