Home /Modules/artificial-intelligence/large_language_models_reasoning.h

large_language_models_reasoning.h

artificial-intelligence/large-language-models/large_language_models_reasoning.h · 185 line(s) · c

#ifndef SLEELA_AI_LLM_REASONING_H
#define SLEELA_AI_LLM_REASONING_H
/*
 * SLeeLa Reasoning Language Model (RLM) layer.
 *
 * A neuro-symbolic reasoning controller that turns a plain next-token LLM
 * (sllm_backend) into a model that reasons: it decomposes a question, proposes
 * intermediate steps as an explicit chain of thought, REFLECTS on and critiques
 * each step, VERIFIES steps through a pluggable checker, BACKTRACKS when a path
 * fails, and only then commits an answer.
 *
 * This matches the current research consensus the SLeeLa project adopted
 * (see REASONING.md): chain-of-thought is a token-level behavior; the gains of
 * a reasoning model come from the control procedure (test-time compute,
 * self-verification, backtracking) plus an external verifier, NOT from changing
 * the vocabulary. The LLM supplies PROPOSALS and plausibility; the verifier
 * supplies SOUNDNESS. For deductive subjects a symbolic verifier (e.g. a bridge
 * to lib/deliberation) should be supplied; for open subjects a weaker critic is
 * used and the engine reports lower confidence rather than claiming proof.
 *
 * The layer bundles NO model: it drives a caller-supplied sllm_backend and an
 * optional caller-supplied verifier. It is an integration contract.
 *
 * Design goals: sophistication, nuance, and reflection. The engine is tuned for
 * subjects that are mainly philosophical, mathematical, or religious, where a
 * single confident answer is often wrong and the honest output is a reasoned,
 * self-aware position with its assumptions, objections, and confidence exposed.
 */
#include "large_language_models.h"
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#if defined(_WIN32) && defined(SLEELA_AI_SHARED)
# if defined(SLEELA_AI_BUILD)
#  define SLLMR_API __declspec(dllexport)
# else
#  define SLLMR_API __declspec(dllimport)
# endif
#elif defined(__GNUC__) && defined(SLEELA_AI_SHARED)
# define SLLMR_API __attribute__((visibility("default")))
#else
# define SLLMR_API
#endif

#define SLLMR_ABI_VERSION 1u

typedef struct sllmr_engine sllmr_engine;

typedef enum sllmr_status {
 SLLMR_OK=0, SLLMR_INVALID_ARGUMENT=1, SLLMR_OUT_OF_MEMORY=2,
 SLLMR_BACKEND_ERROR=3, SLLMR_NOT_LOADED=4, SLLMR_CANCELLED=5,
 SLLMR_NO_SOUND_PATH=6, SLLMR_UNSUPPORTED=7
} sllmr_status;

/* Subject mode steers reflection depth, how strongly the verifier is trusted,
   and how confidence is reported. These are NOT separate models or vocabularies
   -- they are controller policies over the same backend. */
typedef enum sllmr_subject {
 SLLMR_SUBJECT_GENERAL=0,     /* balanced default */
 SLLMR_SUBJECT_MATH=1,        /* expects a symbolic/numeric verifier; seeks proof */
 SLLMR_SUBJECT_PHILOSOPHY=2,  /* dialectic: surface assumptions, steelman objections */
 SLLMR_SUBJECT_RELIGION=3,    /* interpretive: attribute claims to traditions, no proof-claims */
 SLLMR_SUBJECT_CODE=4         /* procedural programming: summarize, dry-run/state-track,
                                 refactor/translate; expects a code verifier (compile/test/trace) */
} sllmr_subject;

/* The role a step plays in the chain of thought. */
typedef enum sllmr_step_kind {
 SLLMR_STEP_DECOMPOSE=0,  /* split the problem / name sub-questions */
 SLLMR_STEP_ASSUMPTION=1, /* an explicit premise the path depends on */
 SLLMR_STEP_DEDUCTION=2,  /* a claimed logical/mathematical consequence */
 SLLMR_STEP_INDUCTION=3,  /* a generalization from cases / evidence */
 SLLMR_STEP_OBJECTION=4,  /* a counterargument / steelman against the path */
 SLLMR_STEP_REFLECTION=5, /* self-critique of the path so far */
 SLLMR_STEP_REVISION=6,   /* a correction after reflection/verification */
 SLLMR_STEP_CONCLUSION=7  /* the committed position for this path */
} sllmr_step_kind;

/* A verifier's judgement of one step. A verifier NEVER fabricates support: when
   it cannot decide, it returns UNKNOWN, and the engine treats UNKNOWN honestly
   (it does not promote an unknown step to "verified"). */
typedef enum sllmr_verdict {
 SLLMR_VERDICT_UNKNOWN=0,   /* cannot determine (open/interpretive, or no checker) */
 SLLMR_VERDICT_SUPPORTED=1, /* consistent / entailed given the stated assumptions */
 SLLMR_VERDICT_REFUTED=2    /* contradicts assumptions or a known fact -> backtrack */
} sllmr_verdict;

/* One reasoning step, borrowed for the lifetime of the callback only. */
typedef struct sllmr_step {
 uint32_t index;            /* 0-based position within the current path */
 uint32_t depth;            /* backtrack depth; 0 = first attempt */
 sllmr_step_kind kind;
 const char *text;          /* the step's natural-language content (UTF-8) */
 sllmr_verdict verdict;     /* the verifier's judgement of this step */
 double confidence;         /* engine confidence in this step, [0,1] */
} sllmr_step;

/* ---- Verifier contract (the symbolic / critic half) ----
   Given the question, the accumulated prior steps, and a candidate step, decide
   whether the candidate is supported. 'note_out'/'note_cap' let the verifier
   return a short rationale (optional; may be left empty). Returning
   SLLMR_VERDICT_UNKNOWN is always acceptable and never penalized as a failure.
   The verifier and its user_data are borrowed and must outlive the engine. */
typedef struct sllmr_verifier {
 uint32_t abi_version;
 const char *name;
 void *user_data;
 sllmr_verdict (*check)(void *user_data,
                        sllmr_subject subject,
                        const char *question,
                        const sllmr_step *prior, size_t prior_count,
                        const sllmr_step *candidate,
                        char *note_out, size_t note_cap);
} sllmr_verifier;

/* Controller policy. Zero-initialize then sllmr_options_init for defaults. */
typedef struct sllmr_options {
 uint32_t abi_version;
 sllmr_subject subject;
 uint32_t max_steps;        /* hard cap on steps per path (test-time compute budget) */
 uint32_t max_backtracks;   /* how many times a refuted path may be abandoned and retried */
 uint32_t reflection_every; /* insert a REFLECTION step every N steps (0 = only at end) */
 double   min_confidence;   /* a CONCLUSION below this is reported as tentative */
 int      require_verified; /* if nonzero, a CONCLUSION must rest only on non-refuted,
                               and (for MATH) on SUPPORTED, steps or the path fails */
 uint64_t seed;             /* forwarded to the backend for deterministic decoding */
} sllmr_options;

/* Streamed observation of the reasoning process. Any callback may be NULL.
   Return 0 from on_step to request cancellation (yields SLLMR_CANCELLED). */
typedef struct sllmr_trace {
 void *user_data;
 int  (*on_step)(void *user_data, const sllmr_step *step);     /* each step as it is formed */
 void (*on_backtrack)(void *user_data, uint32_t from_depth, const char *reason);
} sllmr_trace;

/* The committed outcome. Strings are owned by the result and freed by
   sllmr_result_free. 'steps' is the final, accepted path. */
typedef struct sllmr_result {
 char *answer;              /* the committed position (UTF-8), may be tentative */
 char *summary;             /* a short reflective summary of how it was reached */
 sllmr_step *steps;         /* the accepted reasoning path */
 size_t step_count;
 double confidence;         /* overall confidence in [0,1] */
 int    verified;           /* nonzero if every load-bearing step is non-refuted
                               (and SUPPORTED where the subject demands proof) */
 int    tentative;          /* nonzero if confidence < min_confidence or subject is open */
 uint32_t backtracks;       /* how many paths were abandoned */
} sllmr_result;

SLLMR_API const char *sllmr_status_string(sllmr_status status);
SLLMR_API const char *sllmr_subject_name(sllmr_subject subject);
SLLMR_API const char *sllmr_step_kind_name(sllmr_step_kind kind);
SLLMR_API const char *sllmr_verdict_name(sllmr_verdict verdict);

SLLMR_API sllmr_status sllmr_options_init(sllmr_options *options);

/* Create a reasoning engine over a loaded LLM engine and an OPTIONAL verifier
   (pass NULL for a critic-free, LLM-only run that can still reflect/backtrack
   on self-critique but reports lower confidence). Both are borrowed. */
SLLMR_API sllmr_status sllmr_engine_create(sllm_engine *llm,
                                           const sllmr_verifier *verifier,
                                           sllmr_engine **out_engine);
SLLMR_API void sllmr_engine_destroy(sllmr_engine *engine);
SLLMR_API const char *sllmr_engine_verifier_name(const sllmr_engine *engine);

/* Reason about 'question'. On SLLMR_OK, *out_result is filled and must be
   released with sllmr_result_free. On SLLMR_NO_SOUND_PATH the engine exhausted
   its backtracks without a path meeting require_verified; *out_result still
   holds the best (tentative) path for inspection. */
SLLMR_API sllmr_status sllmr_reason(sllmr_engine *engine,
                                    const char *question,
                                    const sllmr_options *options,
                                    const sllmr_trace *trace,
                                    sllmr_result *out_result);

SLLMR_API void sllmr_result_free(sllmr_result *result);

#ifdef __cplusplus
}
#endif
#endif