sync
This commit is contained in:
+419
@@ -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
@@ -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
@@ -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?
|
||||
@@ -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?
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user