LLMConnection.h

Go to the documentation of this file.

#if !defined(_LLMCONNECTION_H_)
#define _LLMCONNECTION_H_
 
#pragma once
 
#include "Utils.h"
#include "xml_parser.h"
 
#include <string>
#include <vector>
 
namespace   cmlabs{
 
// ============================================================================
//  LLMConnection (T1.1 step 1.1a)
//
//  Named, node-owned connection object to an LLM endpoint, configured from
//  the reserved <llm> named-connection XML element (D1/F1.8) which contains
//  an <llmvendor> vendor-descriptor sub-block:
//
//    <llm name="main" apikeyref="OPENAI_API_KEY" global="true" schemaversion="1"
//         maxtokensperrequest="4096" maxrequestspermin="60"
//         maxconcurrent="2" costceiling="10.0">
//      <llmvendor type="openai" endpoint="https://api.openai.com/v1/chat/completions">
//        <header name="Authorization" value="Bearer %apikey%"/>
//        <requesttemplate>{"model":"%model%","messages":[...]}</requesttemplate>
//        <responsetemplate>choices[0].message.content</responsetemplate>
//        <models default="gpt-4o">
//          <model name="gpt-4o"/>
//          <model name="gpt-4o-mini"/>
//        </models>
//      </llmvendor>
//    </llm>
//
//  Secrets are NEVER inline in the XML (Q-C). `apikeyref` is an indirect
//  reference, resolved at configure() time:
//    apikeyref="env:NAME"    -> environment variable NAME (set, non-empty)
//    apikeyref="file:/path"  -> whole file contents, trailing newline/
//                               whitespace trimmed (single-line key files)
//    apikeyref="NAME"        -> legacy bare form: env var NAME, else a
//                               key=value entry in optional `secretsfile`
//  A missing env var or unreadable file fails typed at connect() with
//  LLM_ERR_SECRET_UNRESOLVED; the secret value (and the failure detail)
//  never appears in logs, errors, or getSystemStatus(). An inline `apikey`
//  attribute or <apikey> child is a typed configuration error
//  (LLM_ERR_CONFIG_INLINE_SECRET).
//
//  C13 constraint fields (max tokens/request, max requests/min, max
//  concurrent, optional cost ceiling) are parsed and stored only — no
//  enforcement logic in this step.
//
//  Networking mode A (blocking request/reply over NetworkManager::
//  makeHTTPRequest) is implemented in step 1.1b: connect() validates config +
//  resolved secret and marks the connection live (endpoint reachability is
//  checked lazily, on the first interact() — the underlying HTTP client is
//  connectionless/blocking, so there is nothing to dial eagerly); interact()
//  shapes the request from <requesttemplate> (%model%/%input%) and the
//  configured headers (%apikey%/%model%), sends it, and extracts the reply
//  text via the <responsetemplate> JSON path. reset() drops the live state
//  but retains config and the final stats record (ended=true). Streaming
//  (mode B) is step 1.2; constraint ENFORCEMENT is a later step.
// ============================================================================
 
// Typed result codes for all LLMConnection operations.
enum LLMResult {
    LLM_OK = 0,
    LLM_ERR_NOT_CONFIGURED,         // API used before a successful configure()
    LLM_ERR_NOT_CONNECTED,          // no live connection (networking is step 1.1b)
    LLM_ERR_NOT_IMPLEMENTED,        // behaviour deferred to a later step
    LLM_ERR_CONFIG_EMPTY,           // missing/empty <llm> element
    LLM_ERR_CONFIG_NOT_LLM,         // element is not an <llm> element
    LLM_ERR_CONFIG_PARSE,           // XML string did not parse
    LLM_ERR_CONFIG_NO_NAME,         // <llm> is a NAMED connection: name required
    LLM_ERR_CONFIG_NO_VENDOR,       // missing <llmvendor> sub-block
    LLM_ERR_CONFIG_UNKNOWN_VENDOR,  // unrecognised <llmvendor type="...">
    LLM_ERR_CONFIG_NO_ENDPOINT,     // missing endpoint URL
    LLM_ERR_CONFIG_INLINE_SECRET,   // inline apikey in XML — use apikeyref
    LLM_ERR_CONFIG_INVALID,         // other structural configuration error
    LLM_ERR_UNKNOWN_MODEL,          // selectModel() name not in the model list
    LLM_ERR_SECRET_UNRESOLVED,      // apikeyref set but no secret could be resolved
    LLM_ERR_NO_INPUT,               // interact() called with empty input
    LLM_ERR_HTTP_UNREACHABLE,       // endpoint unreachable / no HTTP reply
    LLM_ERR_HTTP,                   // endpoint replied with a non-200 status
    LLM_ERR_REPLY_PARSE,            // reply body missing/malformed vs responsetemplate
    LLM_ERR_CONFIG_BAD_TRANSPORT,   // unrecognised <llmvendor transport="...">
    LLM_ERR_STREAM_CANCELLED        // streaming interact stopped early by the sink
};
 
// Human-readable name for an LLMResult (for logs and typed-error reporting).
const char* LLMResultText(LLMResult result);
 
// Vendor family recognised from <llmvendor type="...">. "custom" is allowed
// for config-only vendors that fully specify their own HTTP shape.
enum LLMVendorType {
    LLM_VENDOR_NONE = 0,
    LLM_VENDOR_OPENAI,
    LLM_VENDOR_ANTHROPIC,
    LLM_VENDOR_BEDROCK,
    LLM_VENDOR_GOOGLE,
    LLM_VENDOR_CUSTOM
};
 
const char* LLMVendorTypeText(LLMVendorType type);
 
// Streaming wire format used by mode B (T1.1 step 1.2c). Resolved ONCE at
// configure() time from <llmvendor transport="sse|eventstream|chunked">, or
// by vendor default when the attribute is absent (bedrock -> eventstream,
// everything else -> sse). Callers never branch on vendor: they just call
// interactStream() and the connection drives the right decoder internally.
enum LLMStreamTransport {
    LLM_STREAM_NONE = 0,     // unconfigured / vendor does not stream
    LLM_STREAM_SSE,          // chunked transfer + text/event-stream SSE events
    LLM_STREAM_EVENTSTREAM,  // AWS/Bedrock binary eventstream framing
    LLM_STREAM_CHUNKED       // raw chunked-transfer body, no event framing
};
 
const char* LLMStreamTransportText(LLMStreamTransport transport);
 
// Sink for incremental streaming output (mode B). Return true to continue,
// false to cancel the stream early (interactStream() then returns
// LLM_ERR_STREAM_CANCELLED). `token` is the decoded incremental text (NOT
// raw wire bytes); `userData` is the pointer given to interactStream().
typedef bool (*LLMStreamCallback)(const char* token, uint32 size, void* userData);
 
// One configured HTTP header (value may contain %apikey%/%model% templates).
struct LLMHeader {
    std::string name;
    std::string value;
};
 
// C13 per-connection constraints — parsed and stored in this step, enforced
// in a later step. Values <= 0 (or < 0 for costCeiling) mean "not set".
struct LLMConstraints {
    int32   maxTokensPerRequest;
    int32   maxRequestsPerMin;
    int32   maxConcurrent;
    double  costCeiling;
 
    LLMConstraints() : maxTokensPerRequest(0), maxRequestsPerMin(0),
        maxConcurrent(0), costCeiling(-1.0) {}
};
 
// Connection statistics (uptime, bytes, tokens, cost). All-zero until
// networking lands in later steps; retained after disconnect (ended=true).
struct LLMStats {
    uint64  uptimeMS;
    uint64  bytesSent;
    uint64  bytesReceived;
    uint64  requestCount;
    uint64  tokensIn;
    uint64  tokensOut;
    uint64  replyChunks;   // streamed token chunks delivered (mode B)
    double  cost;
    bool    ended;
 
    LLMStats() : uptimeMS(0), bytesSent(0), bytesReceived(0),
        requestCount(0), tokensIn(0), tokensOut(0), replyChunks(0),
        cost(0.0), ended(false) {}
};
 
// 1.2d-i: owner-notification hook. The owning Node registers a callback so it
// is told when this connection ends (reset() or destruction) and can retain a
// final stats snapshot without holding a dangling pointer. Plain C callback to
// keep CMSDK independent of the Psyclone Node type.
class LLMConnection;
typedef void (*LLMOwnerEndCallback)(void* owner, LLMConnection* connection,
    const LLMStats& finalStats);
 
class LLMConnection {
public:
    LLMConnection();
    ~LLMConnection();
 
    // ---- Ownership (1.2d-i) --------------------------------------------------
    // Set (or clear, with NULLs) the owner-end callback; invoked at most once
    // per connect()..end cycle, from reset() or the destructor.
    void setOwner(void* owner, LLMOwnerEndCallback callback);
 
    // ---- Configuration -----------------------------------------------------
    // Parse an <llm> element (containing an <llmvendor> sub-block). On any
    // error the connection stays/becomes unconfigured and a typed error is
    // returned; bad config must never crash.
    LLMResult configure(const XMLNode& llmNode);
    // Convenience: parse the <llm> element from an XML string first.
    LLMResult configureFromString(const char* xml);
 
    bool isConfigured() const { return configured; }
    LLMResult getLastError() const { return lastError; }
 
    // ---- Parsed fields -----------------------------------------------------
    const std::string& getName() const           { return name; }
    LLMVendorType getVendorType() const          { return vendorType; }
    const std::string& getVendorTypeName() const { return vendorTypeName; }
    const std::string& getEndpoint() const       { return endpoint; }
    bool isGlobal() const                        { return globalConnection; }
    const std::string& getSchemaVersion() const  { return schemaVersion; }
    const std::string& getAPIKeyRef() const      { return apiKeyRef; }
    // True if apikeyref resolved to a secret (env var or secretsfile entry).
    // The secret value itself is never exposed through the public API.
    bool hasResolvedSecret() const               { return !apiKeySecret.empty(); }
    const std::string& getRequestTemplate() const  { return requestTemplate; }
    const std::string& getResponseTemplate() const { return responseTemplate; }
    const std::vector<LLMHeader>& getHeaders() const { return headers; }
    const LLMConstraints& getConstraints() const { return constraints; }
 
    // ---- Models ------------------------------------------------------------
    // Model names from the parsed <models> list (empty if unconfigured).
    std::vector<std::string> listModels() const;
    // Select a model by name from the parsed list; unknown -> typed error.
    LLMResult selectModel(const char* modelName);
    const std::string& getSelectedModel() const  { return selectedModel; }
 
    // ---- Networking (mode A, step 1.1b) -------------------------------------
    // Validate config + secret and mark connected; starts a fresh stats record.
    // Reachability is verified lazily by the first interact().
    LLMResult connect();
    // Drop the live connection; config is kept, stats retained with ended=true.
    LLMResult reset();
    // One blocking request/reply exchange (mode A). On success `reply` holds
    // the text extracted via the responsetemplate JSON path.
    LLMResult interact(const char* input, std::string& reply);
    // Streaming request (mode B, step 1.2c): sends one request and delivers
    // incremental decoded tokens to `callback` as they arrive; on success
    // `fullReply` (if non-NULL) holds the assembled full text. The wire
    // decoder (SSE / eventstream / chunked) is chosen from the configured
    // stream transport — callers never branch on vendor. Blocking until the
    // stream completes, errors, or the callback cancels.
    LLMResult interactStream(const char* input, LLMStreamCallback callback,
        void* userData, std::string* fullReply = NULL);
    bool isConnected() const                     { return connected; }
    // Transport resolved at configure() time (LLM_STREAM_NONE if unconfigured).
    LLMStreamTransport getStreamTransport() const { return streamTransport; }
 
    // ---- Stats -------------------------------------------------------------
    LLMStats stats() const;
 
private:
    LLMResult fail(LLMResult result);
    LLMResult interactFail(LLMResult result);
    std::string applyTemplates(const std::string& text, const char* input) const;
    // Extract a dotted/indexed JSON path (e.g. choices[0].message.content).
    static bool extractJSONPath(const char* json, uint32 size, const char* path,
        std::string& out);
    void clearConfig();
    LLMResult parseVendor(const XMLNode& vendorNode);
    // Resolve transport from an explicit attribute value (may be NULL/empty)
    // + the already-parsed vendorType default. Sets streamTransport.
    LLMResult resolveStreamTransport(const char* transportAttr);
    void resolveSecret();
    static bool nodeHasInlineSecret(const XMLNode& node);
    // 1.2c-ii: reads the HTTP reply header off `con`, then drives the
    // transport decoder, delivering token text to callback (con is a
    // NetworkConnection*, typed void* to keep networking out of this header).
    LLMResult pumpStreamReply(void* con, LLMStreamCallback callback,
        void* userData, std::string* fullReply);
 
    bool            configured;
    bool            connected;
    LLMResult       lastError;
 
    std::string     name;
    LLMVendorType   vendorType;
    std::string     vendorTypeName;
    std::string     endpoint;
    LLMStreamTransport streamTransport;
    bool            globalConnection;
    std::string     schemaVersion;
    std::string     apiKeyRef;
    std::string     secretsFile;
    std::string     apiKeySecret;      // resolved secret — never logged/exposed
    std::string     requestTemplate;
    std::string     responseTemplate;
    std::vector<LLMHeader> headers;
    LLMConstraints  constraints;
 
    std::vector<std::string> models;
    std::string     selectedModel;
 
    // Extract vendor usage token counts from one reply/event JSON body into
    // currentStats (mode A whole reply and mode B per-event share this).
    void accountUsageJSON(const char* json, uint32 size);
 
    // Invoke the owner-end callback (if set and not yet fired for this cycle).
    void notifyOwnerEnded();
 
    void*               owner;          // opaque owner handle (1.2d-i)
    LLMOwnerEndCallback ownerEndCallback;
    bool                ownerNotified;  // callback fired for current cycle
 
    LLMStats        currentStats;
    volatile bool   cancelRequested;    // set by reset() to abort a live stream
    uint64          connectTimeMS;      // wall-clock ms at connect() (0 = never)
    class NetworkManager* netManager;   // owned; created on connect()
};
 
} // namespace cmlabs
 
#endif // !defined(_LLMCONNECTION_H_)