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.
// ============================================================================

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
};

const char* LLMResultText(LLMResult result);

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);

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);

typedef bool (*LLMStreamCallback)(const char* token, uint32 size, void* userData);

struct LLMHeader {
    std::string name;
    std::string value;
};

struct LLMConstraints {
    int32   maxTokensPerRequest;
    int32   maxRequestsPerMin;
    int32   maxConcurrent;
    double  costCeiling;
 
    LLMConstraints() : maxTokensPerRequest(0), maxRequestsPerMin(0),
        maxConcurrent(0), costCeiling(-1.0) {}
};

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) {}
};
 
class LLMConnection;

typedef void (*LLMOwnerEndCallback)(void* owner, LLMConnection* connection,
    const LLMStats& finalStats);

class LLMConnection {
public:
    LLMConnection();
    ~LLMConnection();
 
    // ---- Ownership ----------------------------------------------------------
    void setOwner(void* owner, LLMOwnerEndCallback callback);
 
    // ---- Configuration -----------------------------------------------------
    LLMResult configure(const XMLNode& llmNode);

    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; }

    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 ------------------------------------------------------------
    std::vector<std::string> listModels() const;

    LLMResult selectModel(const char* modelName);

    const std::string& getSelectedModel() const  { return selectedModel; }
 
    // ---- Networking --------------------------------------------------------
    LLMResult connect();

    LLMResult reset();

    LLMResult interact(const char* input, std::string& reply);
    LLMResult interactStream(const char* input, LLMStreamCallback callback,
        void* userData, std::string* fullReply = NULL);

    bool isConnected() const                     { return connected; }

    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_)