Files
moloapp/src/vendors/mistral/conversations.h
T

111 lines
4.1 KiB
C++

#pragma once
// Conversations API (stateful agents / models with built-in tools):
// /v1/conversations. Start with a model or an agent id, append, restart from an
// entry, read history, delete (explicit). Streamed variants decode the
// ConversationEvents SSE stream (conversation.response.started / .done /
// .error, message.output.delta, tool.execution.*, agent.handoff.*,
// function.call.delta).
#include <functional>
#include <optional>
#include <string>
#include <vector>
#include "vendors/mistral/types.h"
namespace molo::mistral {
struct ConversationInput {
// Either a plain string or an array of entries (MessageInputEntry,
// FunctionResultEntry, ...). Build with text() or entries().
Json value;
static ConversationInput text(const std::string& text);
static ConversationInput entries(const std::vector<Json>& entries);
// A user message entry {"type":"message.input","role":"user","content":text}.
static Json user_entry(const std::string& text);
void validate() const;
};
struct ConversationStartParams {
ConversationInput inputs;
std::string model; // exactly one of model / agent_id
std::string agent_id;
int agent_version = -1; // < 0: not sent
std::string instructions, name, description;
Json tools; // null or array
Json completion_args; // null or object
Json guardrails; // null or array
Json metadata; // null or object
std::optional<bool> store;
std::string handoff_execution; // "", client, server
void validate() const;
Json to_json(bool stream) const;
};
struct ConversationAppendParams {
ConversationInput inputs;
Json completion_args;
Json tool_confirmations; // null or array
std::optional<bool> store;
std::string handoff_execution;
void validate() const;
Json to_json(bool stream) const;
};
struct ConversationRestartParams {
std::string from_entry_id; // required
ConversationInput inputs; // optional: leave value null to send none
Json completion_args;
Json metadata;
std::optional<bool> store;
std::string handoff_execution;
int agent_version = -1;
void validate() const;
Json to_json(bool stream) const;
};
struct ConversationResult {
std::string conversation_id;
Json outputs = Json::array();
TokenUsage usage;
Json raw;
std::string text() const; // message.output entries concatenated
static ConversationResult parse(const Json& doc);
};
struct ConversationEvent {
std::string event; // SSE event name
Json data;
};
class Conversations : public MistralService {
public:
explicit Conversations(std::shared_ptr<llm::ApiClient> client) : MistralService(std::move(client)) {}
ConversationResult start(const ConversationStartParams& params);
ConversationResult append(const std::string& conversation_id, const ConversationAppendParams& params);
ConversationResult restart(const std::string& conversation_id, const ConversationRestartParams& params);
using EventSink = std::function<bool(const ConversationEvent&)>; // false: stop
// Streams; returns the folded result. Throws 502 STREAM_TRUNCATED when the
// stream ends without conversation.response.done (unless the sink stopped it)
// and the server's error when conversation.response.error arrives.
ConversationResult start_stream(const ConversationStartParams& params, const EventSink& sink);
ConversationResult append_stream(const std::string& conversation_id, const ConversationAppendParams& params,
const EventSink& sink);
ConversationResult restart_stream(const std::string& conversation_id, const ConversationRestartParams& params,
const EventSink& sink);
ListPage list(int page = 0, int page_size = 100);
Json get(const std::string& conversation_id);
Json history(const std::string& conversation_id);
Json messages(const std::string& conversation_id);
void remove(const std::string& conversation_id); // explicit, irreversible
private:
ConversationResult run_stream(const char* op, const std::vector<std::string>& ids, const Json& body,
const EventSink& sink);
};
} // namespace molo::mistral