@almadar/std 16.144.0 → 16.145.0

package/behaviors/lolo/ml/atoms/std-ml-classify.lolo

@@ -0,0 +1,121 @@
+app std-ml-classify "1.0.0"
+"Generative rung (R5) — structured LLM verdict from a closed category set, via the llm.classify service seam. Bottom of the fall-through: always answers or fails, never abstains."
+
+orbital MlClassifyOrbital {
+
+  entity ClassifierVerdict [runtime] {
+    text         : string   = ""
+    category     : string   = ""
+    confidence   : float    = 0
+    reasoning    : string   = ""
+    errorMessage : string   = ""
+    request      : object   = {}
+    status       : "idle" | "classifying" | "done" = idle
+  }
+
+  trait ClassifyRun -> ClassifierVerdict [lifecycle, instance] {
+    initial: idle
+
+    config {
+      categories : [string] = []
+        @label "Categories"
+        @description "Closed set of category labels the LLM must choose from"
+        @tier "domain"
+      provider : string = ""
+        @label "Provider"
+        @description "Reserved for provider selection; LLMServiceActions.classify (packages/almadar-llm/src/contracts.ts) takes no provider param today, so this knob is not forwarded to the call"
+        @tier "infra"
+      model : string = ""
+        @label "Model"
+        @description "Model override forwarded to the classify call"
+        @tier "infra"
+    }
+
+    state idle {
+      INIT -> idle
+        (set @entity.text "")
+        (set @entity.category "")
+        (set @entity.confidence 0)
+        (set @entity.reasoning "")
+        (set @entity.errorMessage "")
+        (set @entity.request {})
+        (set @entity.status idle)
+
+      CLASSIFY -> classifying
+        (set @entity.text ?text)
+        (set @entity.request ?request)
+        (set @entity.status classifying)
+        (call-service "llm" "classify" { text: ?text, categories: @config.categories, model: @config.model }
+          { emit: { success: CLASSIFIED_RAW, failure: CLASSIFY_CALL_FAILED } })
+    }
+
+    state classifying {
+      CLASSIFIED_RAW -> done
+        (set @entity.category ?category)
+        (set @entity.confidence ?confidence)
+        (set @entity.reasoning ?reasoning)
+        (set @entity.status done)
+        (emit CLASSIFIED { category: @entity.category, confidence: @entity.confidence, reasoning: @entity.reasoning })
+
+      CLASSIFY_CALL_FAILED -> done
+        (set @entity.category "")
+        (set @entity.confidence 0)
+        (set @entity.reasoning "")
+        (set @entity.errorMessage ?error)
+        (set @entity.status done)
+        (emit CLASSIFY_FAILED { error: @entity.errorMessage })
+    }
+
+    state done {
+      INIT -> done
+        (set @entity.status done)
+      RESET -> idle
+        (set @entity.text "")
+        (set @entity.category "")
+        (set @entity.confidence 0)
+        (set @entity.reasoning "")
+        (set @entity.errorMessage "")
+        (set @entity.request {})
+        (set @entity.status idle)
+    }
+
+    emits {
+      CLASSIFIED_RAW {
+        category   : string!
+        confidence : number!
+        reasoning  : string!
+      }
+        @description "Raw llm.classify service result, flattened onto the payload by the call-service effect executor"
+        @tier "secondary"
+
+      CLASSIFY_CALL_FAILED {
+        error : string!
+      }
+        @description "call-service classify failure signal"
+        @tier "secondary"
+
+      CLASSIFIED -> external {
+        category   : string!
+        confidence : float!
+        reasoning  : string!
+      }
+        @description "Structured LLM verdict — closed-set category with confidence and reasoning"
+        @tier "primary"
+
+      CLASSIFY_FAILED -> external {
+        error : string!
+      }
+        @description "The classify service call failed; this rung never abstains, only answers or fails"
+        @tier "primary"
+    }
+
+    listens {
+      CLASSIFY {
+        text : string!
+        request : object
+      }
+    }
+  }
+
+  page "/ml-classify" as MlClassifyPage -> ClassifyRun
+}

package/behaviors/lolo/ml/atoms/std-ml-exact-check.lolo

@@ -0,0 +1,90 @@
+app std-ml-exact-check "1.0.0"
+"Rung R0 of the intelligence ladder — normalizes and compares a candidate value against a key value; abstains on no match."
+
+orbital MlExactCheckOrbital {
+
+  entity ExactCheck [runtime] {
+    matched : boolean = false
+    status  : "idle" | "checked" = idle
+  }
+
+  trait ExactCheckRun -> ExactCheck [lifecycle, instance] {
+    initial: idle
+
+    config {
+      caseSensitive : boolean = false
+        @label "Case sensitive"
+        @description "Compare candidate and key with case sensitivity; off lowercases both sides before comparing"
+        @tier "policy"
+      trimWhitespace : boolean = true
+        @label "Trim whitespace"
+        @description "Strip leading and trailing whitespace from both sides before comparing"
+        @tier "policy"
+      numericTolerance : float = 0
+        @label "Numeric tolerance"
+        @description "Absolute tolerance applied when both candidate and key are numbers; 0 requires an exact numeric match"
+        @tier "policy"
+    }
+
+    state idle {
+      INIT -> idle
+        (set @entity.matched false)
+        (set @entity.status idle)
+      CHECK -> checked
+        (let ((bothNumeric (and (validate/number ?candidate) (validate/number ?key)))
+              (candStr (str/concat ?candidate))
+              (keyStr (str/concat ?key))
+              (candTrim (if @config.trimWhitespace (str/trim @candStr) @candStr))
+              (keyTrim (if @config.trimWhitespace (str/trim @keyStr) @keyStr))
+              (candNorm (if @config.caseSensitive @candTrim (str/lower @candTrim)))
+              (keyNorm (if @config.caseSensitive @keyTrim (str/lower @keyTrim)))
+              (isMatch (if @bothNumeric
+                         (<= (math/abs (- ?candidate ?key)) @config.numericTolerance)
+                         (== @candNorm @keyNorm))))
+          (if @isMatch
+            (do
+              (set @entity.matched true)
+              (set @entity.status checked)
+              (emit EXACT_MATCHED { candidate: ?candidate, key: ?key }))
+            (do
+              (set @entity.matched false)
+              (set @entity.status checked)
+              (emit EXACT_UNMATCHED { candidate: ?candidate, key: ?key, request: ?request }))))
+    }
+
+    state checked {
+      INIT -> checked
+        (set @entity.status checked)
+      RESET -> idle
+        (set @entity.matched false)
+        (set @entity.status idle)
+    }
+
+    emits {
+      EXACT_MATCHED -> external {
+        candidate : any!
+        key : any!
+      }
+        @description "Fired when the candidate exactly equals the key under the configured normalization"
+        @tier "primary"
+
+      EXACT_UNMATCHED -> external {
+        candidate : any!
+        key : any!
+        request : object
+      }
+        @description "Abstain — candidate does not equal the key; the next rung should take over. request echoes the originating request untouched so the next rung can project its own inputs out of it"
+        @tier "primary"
+    }
+
+    listens {
+      CHECK {
+        candidate : any!
+        key : any!
+        request : object
+      }
+    }
+  }
+
+  page "/ml-exact-check" as MlExactCheckPage -> ExactCheckRun
+}

package/behaviors/lolo/ml/atoms/std-ml-infer.lolo

@@ -0,0 +1,141 @@
+app std-ml-infer "1.0.0"
+"std-ml-infer — the learned rung (R4) of the intelligence ladder, and the seam between a .lolo circuit and a trained model deployed on masar (or off-the-shelf HuggingFace weights) reached through the ml service. Sends the caller-supplied input straight to call-service ml infer, then guards the raw output before it ever becomes an effect: validates it against the declared outputContract, clamps it into range, and only then decides. Emits INFERRED when the output satisfies the contract and confidence clears confidenceFloor — carrying the clamped output, confidence, and an empty violations list. Otherwise abstains with INFER_ABSTAINED, whose reason is one of: low confidence (contract satisfied but below floor, violations empty), contract violation (violations populated via contract/violations for diagnosis), or unavailable (the service call itself failed — a masar cold start or a down endpoint, never surfaced as a user-visible error). Use when a numeric or tensor-shaped model answer needs a licensed guard before becoming a decision — classification scores, regressions, embedding-derived predictions — and the next rung (R5 generative) should take over on any abstain."
+
+type Range = { min: float!, max: float! }
+type OutputContract = { shape: [int], ranges: Map string Range }
+
+orbital MlInferOrbital {
+
+  entity Inference [runtime] {
+    input      : object   = {}
+    output     : [float]  = []
+    confidence : float    = 0
+    violations : [object] = []
+    reason     : string   = ""
+    request    : object   = {}
+    status     : "idle" | "inferring" | "resolved" = idle
+  }
+
+  trait InferenceRun -> Inference [lifecycle, instance] {
+    initial: idle
+
+    config {
+      model : string = ""
+        @label "Model reference"
+        @description "hf:<id> for off-the-shelf weights, or a masar checkpoint id, forwarded to the ml service infer action"
+        @tier "infra"
+      confidenceFloor : float = 0.7
+        @label "Confidence floor"
+        @description "Minimum service-reported confidence required to answer; below this the atom abstains with reason low confidence"
+        @tier "policy"
+      outputContract : OutputContract = { ranges: {} }
+        @label "Output contract"
+        @description "Declared shape and per-dimension ranges the model output must satisfy; a failing check abstains with reason contract violation. Omit shape to assert ranges only — an empty shape [] asserts a SCALAR output, it does not mean unconstrained"
+        @tier "domain"
+    }
+
+    state idle {
+      INIT -> idle
+        (set @entity.input {})
+        (set @entity.output [])
+        (set @entity.confidence 0)
+        (set @entity.violations [])
+        (set @entity.reason "")
+        (set @entity.request {})
+        (set @entity.status idle)
+
+      INFER -> inferring
+        (set @entity.input ?input)
+        (set @entity.request ?request)
+        (set @entity.status inferring)
+        (call-service "ml" "infer" { model: @config.model, input: @entity.input }
+          { emit: { success: INFERRED_RAW, failure: INFER_CALL_FAILED } })
+    }
+
+    state inferring {
+      INFERRED_RAW -> resolved
+        (set @entity.output ?output)
+        (set @entity.confidence ?confidence)
+        (let ((validation (contract/validate-output @entity.output @config.outputContract)))
+          (if (object/get @validation "valid")
+            (if (>= @entity.confidence @config.confidenceFloor)
+              (do
+                (set @entity.output (contract/clamp-output @entity.output @config.outputContract))
+                (set @entity.violations [])
+                (set @entity.reason "")
+                (set @entity.status resolved)
+                (emit INFERRED { output: @entity.output, confidence: @entity.confidence, violations: @entity.violations }))
+              (do
+                (set @entity.violations [])
+                (set @entity.reason "low confidence")
+                (set @entity.status resolved)
+                (emit INFER_ABSTAINED { reason: "low confidence", violations: @entity.violations, request: @entity.request })))
+            (do
+              (set @entity.violations (contract/violations @entity.output @config.outputContract))
+              (set @entity.reason "contract violation")
+              (set @entity.status resolved)
+              (emit INFER_ABSTAINED { reason: "contract violation", violations: @entity.violations, request: @entity.request }))))
+
+      INFER_CALL_FAILED -> resolved
+        (set @entity.output [])
+        (set @entity.confidence 0)
+        (set @entity.violations [])
+        (set @entity.reason "unavailable")
+        (set @entity.status resolved)
+        (emit INFER_ABSTAINED { reason: "unavailable", violations: @entity.violations, request: @entity.request })
+    }
+
+    state resolved {
+      INIT -> resolved
+        (set @entity.status resolved)
+      RESET -> idle
+        (set @entity.input {})
+        (set @entity.output [])
+        (set @entity.confidence 0)
+        (set @entity.violations [])
+        (set @entity.reason "")
+        (set @entity.request {})
+        (set @entity.status idle)
+    }
+
+    emits {
+      INFERRED_RAW {
+        output     : [float]!
+        confidence : number!
+      }
+        @description "Raw ml.infer service result, flattened onto the payload by the call-service effect executor"
+        @tier "secondary"
+
+      INFER_CALL_FAILED {
+        error : string!
+      }
+        @description "call-service infer failure signal — a masar cold start or a down endpoint lands here, not as a user-visible error"
+        @tier "secondary"
+
+      INFERRED -> external {
+        output     : [float]!
+        confidence : float!
+        violations : [object]!
+      }
+        @description "The service answered, the output satisfies outputContract, and confidence clears confidenceFloor — output already clamped"
+        @tier "primary"
+
+      INFER_ABSTAINED -> external {
+        reason     : string!
+        violations : [object]!
+        request    : object
+      }
+        @description "The abstain — reason is one of: low confidence, contract violation, unavailable. violations is populated only on the contract violation path. request echoes the originating request untouched so the next rung can project its own inputs out of it"
+        @tier "primary"
+    }
+
+    listens {
+      INFER {
+        input : object!
+        request : object
+      }
+    }
+  }
+
+  page "/ml-infer" as MlInferPage -> InferenceRun
+}

package/behaviors/lolo/ml/atoms/std-ml-label-capture.lolo

@@ -0,0 +1,75 @@
+app std-ml-label-capture "1.0.0"
+"std-ml-label-capture — records a labeled example (input, verdict, source rung, observed outcome) so that expensive top-rung answers become training data for a cheaper rung later. Generic: it knows nothing about grading or students. sampleRate gates what fraction of examples are kept (1 = capture all); sink tags which named destination the example is attributed to."
+orbital MlLabelCaptureOrbital {
+
+  entity LabeledExample [persistent: ml_labels] {
+    id : string! @key
+    input : json @description "The input that was judged." = null
+    verdict : json @description "The verdict/output produced by the rung." = null
+    source : string @description "Which rung produced the verdict." = ""
+    outcome : json @description "The observed ground-truth outcome, once known." = null
+    sink : string @description "Named destination this example is attributed to." = ""
+    recordedAt : number = 0
+  }
+
+  trait LabelCaptureListener -> @rebindable LabeledExample [lifecycle, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (set @entity.input null)
+        (set @entity.verdict null)
+        (set @entity.source "")
+        (set @entity.outcome null)
+        (set @entity.sink "")
+        (set @entity.recordedAt 0)
+      CAPTURE -> idle
+        (set @entity.input ?input)
+        (set @entity.verdict ?verdict)
+        (set @entity.source ?source)
+        (set @entity.outcome ?outcome)
+        (set @entity.sink @config.sink)
+        (set @entity.recordedAt @now)
+        (if (prob/flip @config.sampleRate)
+            (do
+              (persist create LabeledExample {
+                input: @entity.input
+                verdict: @entity.verdict
+                source: @entity.source
+                outcome: @entity.outcome
+                sink: @entity.sink
+                recordedAt: @entity.recordedAt
+              })
+              (emit LABEL_CAPTURED { source: @entity.source, sink: @entity.sink }))
+            null)
+    }
+
+    emits {
+      LABEL_CAPTURED -> external { source : string!, sink : string! }
+        @description "Fired after a labeled example is persisted."
+        @tier "primary"
+    }
+
+    listens {
+      CAPTURE {
+        input : json!
+        verdict : json!
+        source : string!
+        outcome : json
+      }
+    }
+
+    config {
+      sink : string = ""
+        @label "Label sink"
+        @description "Named destination this batch of examples is attributed to; interpreted downstream (the physical label store is not yet decided)."
+        @tier "infra"
+      sampleRate : float = 1
+        @label "Sample rate"
+        @description "Fraction of examples to keep (1 = capture all). A prob/flip trial per observation."
+        @tier "policy"
+    }
+  }
+
+  page "/ml-label-capture" as MlLabelCapturePage -> LabelCaptureListener
+}

package/behaviors/lolo/ml/atoms/std-ml-lookup.lolo

@@ -0,0 +1,83 @@
+app std-ml-lookup "1.0.0"
+"Rung R1 of the intelligence ladder — finds the candidate value in a list of accepted values; abstains when nothing matches."
+
+orbital MlLookupOrbital {
+
+  entity KeyLookup [runtime] {
+    matched : boolean = false
+    status  : "idle" | "checked" = idle
+  }
+
+  trait LookupRun -> KeyLookup [lifecycle, instance] {
+    initial: idle
+
+    config {
+      matchField : string = ""
+        @label "Match field"
+        @description "When the accepted list holds objects rather than scalars, the field to compare against the candidate; empty compares each element itself"
+        @tier "domain"
+      normalize : boolean = true
+        @label "Normalize"
+        @description "Trim and lowercase both sides before comparing"
+        @tier "policy"
+    }
+
+    state idle {
+      INIT -> idle
+        (set @entity.matched false)
+        (set @entity.status idle)
+      LOOKUP -> checked
+        (let ((candStr (str/concat ?candidate))
+              (candNorm (if @config.normalize (str/lower (str/trim @candStr)) @candStr))
+              (found (array/find ?accepted
+                       (fn item
+                         (let ((raw (if (== @config.matchField "") @item (object/get @item @config.matchField)))
+                               (rawStr (str/concat @raw))
+                               (rawNorm (if @config.normalize (str/lower (str/trim @rawStr)) @rawStr)))
+                           (== @rawNorm @candNorm))))))
+          (if (!= @found null)
+            (do
+              (set @entity.matched true)
+              (set @entity.status checked)
+              (emit KEY_HIT { candidate: ?candidate, entry: @found }))
+            (do
+              (set @entity.matched false)
+              (set @entity.status checked)
+              (emit KEY_MISS { candidate: ?candidate, request: ?request }))))
+    }
+
+    state checked {
+      INIT -> checked
+        (set @entity.status checked)
+      RESET -> idle
+        (set @entity.matched false)
+        (set @entity.status idle)
+    }
+
+    emits {
+      KEY_HIT -> external {
+        candidate : any!
+        entry : any!
+      }
+        @description "Fired when the candidate matches an entry in the accepted list"
+        @tier "primary"
+
+      KEY_MISS -> external {
+        candidate : any!
+        request : object
+      }
+        @description "Abstain — candidate matches nothing in the accepted list; the next rung should take over. request echoes the originating request untouched so the next rung can project its own inputs out of it"
+        @tier "primary"
+    }
+
+    listens {
+      LOOKUP {
+        candidate : any!
+        accepted : [any]!
+        request : object
+      }
+    }
+  }
+
+  page "/ml-lookup" as MlLookupPage -> LookupRun
+}

package/behaviors/lolo/ml/atoms/std-ml-posterior.lolo

@@ -0,0 +1,104 @@
+app std-ml-posterior "1.0.0"
+"std-ml-posterior — the statistical rung (R2) of the intelligence ladder. Holds a Beta(alpha, beta) belief over an unknown success rate and updates it from boolean observations (Bayesian updating, knowledge tracing, Thompson-sampling prior). After each observation it draws samples from the posterior, computes a credible interval, and decides: MASTERY_REACHED when the mean clears the floor with a tight interval, REMEDIATION_NEEDED when the mean sits at or below the ceiling with the same confidence, or EVIDENCE_INSUFFICIENT — the abstain — when the interval is still too wide to trust. Use when a hand-tuned score needs to become a belief that can say 'not enough evidence yet' (mastery, skill, risk, preference, difficulty)."
+orbital MlPosteriorOrbital {
+
+  entity Posterior [runtime] {
+    alpha : float @description "Beta distribution success count (prior + observed successes)." = 1
+    beta : float @description "Beta distribution failure count (prior + observed failures)." = 1
+    mean : float @description "Posterior mean: alpha / (alpha + beta)." = 0
+    intervalLow : float @description "Lower bound of the last computed credible interval." = 0
+    intervalHigh : float @description "Upper bound of the last computed credible interval." = 0
+    observations : int @description "Number of observations folded into the posterior so far." = 0
+    status : "idle" | "insufficient" | "mastered" | "remediate" = idle
+  }
+
+  trait PosteriorBelief -> @rebindable Posterior [lifecycle, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (set @entity.alpha @config.priorAlpha)
+        (set @entity.beta @config.priorBeta)
+        (set @entity.mean (/ @config.priorAlpha (+ @config.priorAlpha @config.priorBeta)))
+        (set @entity.intervalLow 0)
+        (set @entity.intervalHigh 0)
+        (set @entity.observations 0)
+        (set @entity.status idle)
+      OBSERVE -> idle
+        (set @entity.alpha (if ?outcome (+ @entity.alpha 1) @entity.alpha))
+        (set @entity.beta (if ?outcome @entity.beta (+ @entity.beta 1)))
+        (set @entity.observations (+ @entity.observations 1))
+        (set @entity.mean (/ @entity.alpha (+ @entity.alpha @entity.beta)))
+        (let ((samples (prob/sample @config.sampleCount (prob/beta @entity.alpha @entity.beta)))
+              (interval (prob/credible-interval @samples 0.05))
+              (low (array/nth @interval 0))
+              (high (array/nth @interval 1))
+              (width (- @high @low)))
+          (do
+            (set @entity.intervalLow @low)
+            (set @entity.intervalHigh @high)
+            (if (> @width @config.intervalWidthMax)
+                (do
+                  (set @entity.status insufficient)
+                  (emit EVIDENCE_INSUFFICIENT { mean: @entity.mean, intervalLow: @low, intervalHigh: @high }))
+                (if (>= @entity.mean @config.masteryFloor)
+                    (do
+                      (set @entity.status mastered)
+                      (emit MASTERY_REACHED { mean: @entity.mean, intervalLow: @low, intervalHigh: @high }))
+                    (if (<= @entity.mean @config.remediationCeiling)
+                        (do
+                          (set @entity.status remediate)
+                          (emit REMEDIATION_NEEDED { mean: @entity.mean, intervalLow: @low, intervalHigh: @high }))
+                        (do
+                          (set @entity.status insufficient)
+                          (emit EVIDENCE_INSUFFICIENT { mean: @entity.mean, intervalLow: @low, intervalHigh: @high })))))))
+    }
+
+    emits {
+      MASTERY_REACHED -> external { mean : float!, intervalLow : float!, intervalHigh : float! }
+        @description "The posterior mean clears masteryFloor with a credible interval narrow enough to trust."
+        @tier "primary"
+      REMEDIATION_NEEDED -> external { mean : float!, intervalLow : float!, intervalHigh : float! }
+        @description "The posterior mean is at or below remediationCeiling with a credible interval narrow enough to trust."
+        @tier "primary"
+      EVIDENCE_INSUFFICIENT -> external { mean : float!, intervalLow : float!, intervalHigh : float! }
+        @description "The abstain — the credible interval is still wider than intervalWidthMax, so no verdict is licensed yet."
+        @tier "primary"
+    }
+
+    listens {
+      OBSERVE {
+        outcome : boolean!
+      }
+    }
+
+    config {
+      priorAlpha : float = 1
+        @label "Prior alpha"
+        @description "Beta prior success pseudo-count before any observation."
+        @tier "domain"
+      priorBeta : float = 1
+        @label "Prior beta"
+        @description "Beta prior failure pseudo-count before any observation."
+        @tier "domain"
+      masteryFloor : float = 0.8
+        @label "Mastery floor"
+        @description "Posterior mean at or above this, with a tight interval, licenses MASTERY_REACHED."
+        @tier "policy"
+      remediationCeiling : float = 0.4
+        @label "Remediation ceiling"
+        @description "Posterior mean at or below this, with a tight interval, licenses REMEDIATION_NEEDED."
+        @tier "policy"
+      intervalWidthMax : float = 0.3
+        @label "Max credible-interval width"
+        @description "Above this width the posterior is too uncertain to decide — abstain with EVIDENCE_INSUFFICIENT."
+        @tier "policy"
+      sampleCount : int = 200
+        @label "Posterior sample count"
+        @description "Number of Monte Carlo draws from the Beta posterior used to estimate the credible interval."
+        @tier "infra"
+    }
+  }
+
+  page "/ml-posterior" as MlPosteriorPage -> PosteriorBelief
+}