Agent parameters are usually frozen at deploy time: one model, one temperature, one retry budget for every task the agent will ever see. NoeticOS is the JIT compiler for Massive Intelligence (IM) agents. It classifies every task, learns the optimal parameters per task class with confidence-bound bandits, promotes changes only through deterministic canary rollouts with automatic rollback, and records every decision with the numeric evidence behind it. Catch the optimum while it runs.
pnpm add @takk/noeticoscreateNoeticOS() wires a classifier, per-class bandits, a canary rollout judge, an audit
log, and pluggable state behind two calls: recommend() before the task,
report() after it.
Sorts every task into one of 10 task kinds plus an unknown fallback (factual-qa,
code-generation, extraction, summarization, and more) from
keyword and shape signals: prompt length, tool count, caller metadata. A caller-asserted kind overrides
the classifier entirely.
Parameters are learned per task class, not per agent average, and every recommendation reports the classification confidence and the exact signals that fired.
One discounted UCB1-tuned bandit per parameter dimension and task class, across six dimensions:
model, temperature, topP, maxTurns,
retryBudget, contextShare. A global exponential discount tick keeps the
statistics tracking non-stationary workloads: idle arms lose effective count, so stale optima are
re-challenged instead of frozen out.
The engine keeps adapting when the workload shifts, without a retraining step or an offline pipeline.
Cohort assignment is deterministic: a seeded hash sends a fixed share of executions (10% by default) to the canary, which differs from the baseline in exactly one parameter. Promotion is statistically gated; rollback fires earlier by design, backed by a hard quality floor and a futility bound.
Any reward difference is attributable to the single parameter under test, so every verdict has one cause.
Every promotion, rollback, freeze, and release is appended to an immutable decision log: type, parameter, from and to values, human-readable reasoning, and the numeric evidence (means, confidence bounds, sample counts) that justified it.
When someone asks why the temperature changed on Tuesday, the answer is one
decisions() call away, with the statistics attached.
Learned state serializes to a versioned snapshot of aggregate statistics only. memoryState
and fileState ship in the box; any StateBackend with load and
save plugs in. Persistence is best-effort by contract.
A failing backend never blocks recommendation traffic, and profiles survive restarts when you want them to.
Exploration never touches baseline traffic. The canary cohort, 10% of executions by default, differs from the stable configuration in exactly one parameter at a time, and scenario S7 of the CI benchmark re-proves the contract on every run, zero violations allowed.
The riskiest thing the engine ever does is serve a small, audited share of traffic one value away from stable, and it can always show the evidence.
The invariant is stated in the type contract and enforced on every code path. The asymmetry is deliberate: a missed improvement costs less than a regression served to baseline traffic.
minSamplesPerArm (8) canary
samples or below the configured confidence (0.95).canaryShare 0.1
by default), so assignment is reproducible run over run.freezeTuning until the world stabilizes.pnpm add @takk/noeticosnpm install @takk/noeticosyarn add @takk/noeticosbun add @takk/noeticosimport { createNoeticOS } from '@takk/noeticos';
const runtime = createNoeticOS({
objective: 'cost',
qualityFloor: { minSuccessRate: 0.9 },
});
// Before the task: the full parameter set for this execution.
const rec = runtime.recommend({
agentId: 'support-bot',
prompt: 'Summarize this incident thread for the on-call engineer.',
});
// rec.parameters -> { temperature: 0.4, topP: 1, maxTurns: 32,
// retryBudget: 1, contextShare: 0.6 }
// rec.cohort -> 'baseline' or 'canary'; rec.reasoning explains every value.
// ... run the agent task with rec.parameters applied ...
// After the task: report what happened.
runtime.report({
executionId: rec.executionId,
latencyMs: 2310,
costUsd: 0.0042,
turns: 3,
finishReason: 'stop',
});runtime.on((event) => {
if (event.type === 'decision.recorded') {
console.log(event.entry.reasoning, event.entry.evidence);
}
});
const audit = runtime.decisions({ agentId: 'support-bot', limit: 20 });
recommend() is synchronous and allocation-light, safe on the hot path. Outcomes with unknown
execution ids are ignored, so a crash between the two calls cannot corrupt learning.
Omitted dimensions get the default arms below; the model dimension is tuned only when
candidates are declared. Locked parameters never enter a canary, and
constraints.baseline overrides any starting value.
| Parameter | Default arms | What it controls |
|---|---|---|
model |
declared ModelCandidate list (no default) |
Which model id serves the class. Tier hints (fast,
balanced, frontier) inform reasoning strings, never rewards. |
temperature |
0, 0.2, 0.4, 0.7, 1.0 |
Sampling temperature. |
topP |
0.9, 1.0 |
Nucleus sampling mass. |
maxTurns |
8, 16, 32, 64 |
Ceiling on agent loop turns per execution. |
retryBudget |
0, 1, 3 |
Retries allowed per execution. |
contextShare |
0.4, 0.6, 0.8 |
Fraction of the context window the agent may fill before NoeticOS recommends trimming. |
Every outcome is scored into a composite reward from quality, cost, and latency terms, normalized
against the running per-class statistics. Presets fix the weights; custom weights are normalized to sum
to 1. Quality uses the explicit qualityScore when reported, otherwise it is derived from the
finish reason, tool failures, and detected tool loops.
| Preset | Quality | Cost | Latency | Use it when |
|---|---|---|---|---|
balanced |
0.5 | 0.25 | 0.25 | Default. No single term dominates. |
cost |
0.35 | 0.5 | 0.15 | Spend is the constraint. The quality floor still applies. |
latency |
0.35 | 0.15 | 0.5 | Interactive agents where waiting is the real cost. |
quality |
0.7 | 0.15 | 0.15 | Correctness-critical work; cost and latency are tiebreakers. |
The CLI ships a synthetic workload that exercises the whole loop. One seed yields one byte-identical transcript; the excerpt below is real output, truncated in the middle. The same tuned-versus-static comparison runs as a 9-scenario benchmark gate in CI.
$ noeticos simulate --executions 2400 --seed 7
decision canary.started factual-qa temperature 0.4 -> 0
decision canary.started creative-writing temperature 0.4 -> 0
decision canary.started extraction temperature 0.4 -> 0
decision canary.promoted factual-qa temperature 0.4 -> 0
decision canary.started factual-qa topP 1 -> 0.9
decision canary.rolledback factual-qa topP 0.9 -> 1
(19 decision lines omitted)
--- summary ---
executions: 2400
decisions: 25 (2 promoted, 9 rolled back)
canary share observed: 0.115
per-kind promoted parameters:
factual-qa: temperature=0 topP=1 maxTurns=32 retryBudget=1 contextShare=0.6
creative-writing: temperature=0.4 topP=1 maxTurns=32 retryBudget=1 contextShare=0.6
extraction: temperature=0.4 topP=1 maxTurns=8 retryBudget=1 contextShare=0.6
counterfactual: identical workload and noise, static baseline versus tuned
static baseline: cost=$17.6000 quality=0.879
noeticos tuned: cost=$8.0000 quality=0.925
delta: cost -54.5% quality +5.3%Same workload, same noise: 54.5% lower cost at 5.3% higher quality than the static baseline, on this synthetic workload. Run it yourself; the transcript will match byte for byte.
Every entry point ships ESM and CJS with its own type declarations. Sizes are brotli over the published build, enforced by size-limit in CI.
@takk/noeticosThe core engine: createNoeticOS, classifier, bandits, rollout judge, decision log,
objective presets, memory and file state. Zero runtime dependencies.
@takk/noeticos/otelOTel GenAI ingestion: taskFromSpan, outcomeFromSpan, and
parametersFromSpan read GenAI semantic-convention spans structurally, importing no
OpenTelemetry package. Prompt content is never extracted.
@takk/noeticos/vercelPackaged Vercel AI SDK middleware: noeticosMiddleware for
wrapLanguageModel applies the recommended temperature and topP per call and reports usage,
latency, and finish reason automatically.
@takk/noeticos/integrationsStructural bridges into the family stack below: sibling signals freeze and release tuning, and learned models feed routing. The siblings are optional peers, never imported.
@takk/noeticos/webBrowser entry: the full engine minus the Node file backend, so bundles never reference
node:fs.
@takk/noeticos/edgeEdge entry for Cloudflare Workers, Vercel Edge, Deno, and Bun. Deterministic seeded PRNG, no platform randomness, no Node-only APIs.
noeticos CLIsimulate runs the deterministic demo, inspect renders a state snapshot,
version prints the package version, and serve starts a local HTTP bridge
that exposes recommend/report to non-Node runtimes, Hermes Agent included:
constant-time bearer-token auth, a non-loopback refusal without a token, JSON content-type
enforcement, and gated CORS preflight.
The numerical layer behind every surface is written from the literature: Welford moments, P2 quantile estimation, the exact one-sided binomial tail, the exact Student t tail via the regularized incomplete beta, Wilson intervals, and discounted UCB1-tuned bounds. Nothing to audit transitively.
One on(listener) call streams the typed engine events: recommendations issued, outcomes
recorded with their reward, every audit decision, loop detection, limit warnings, and tuning releases.
A throwing listener never breaks the engine.
NoeticOS is the adaptive layer of the @takk family. Each sibling owns one concern, and the bridges keep every canary verdict attributable to exactly one cause: tuning freezes while credentials rotate or behavior drifts, and resumes when the world stabilizes.
@takk/keymeshAPI key rotation, failover, and circuit breaking for provider credentials. The bridge freezes tuning while keys are in flux and releases it after a successful rotation.
davccavalcante/keymesh@takk/modelchainModel routing and fallback chains across providers. The read-side bridge exposes the model NoeticOS has learned per agent and task class to any routing strategy.
davccavalcante/modelchain@takk/behavioralaiBehavioral observability for agents: learned fingerprints, drift detection, predictive alerts. Critical drift freezes tuning until the agent recovers, keeping both audit trails truthful.
davccavalcante/behavioralaiIt tunes the runtime parameters of your agents while they run. Before each task,
recommend() returns the full parameter set (model, temperature, topP, maxTurns,
retryBudget, contextShare) learned for that agent and task class. After the task,
report() feeds back what happened. The engine scores each outcome into a reward, updates
per-class bandits, and converges on the values that maximize your objective.
A JIT compiler observes a running program and recompiles its hot paths with better optimizations, without stopping it. NoeticOS does the same for agent runtime parameters: it observes executions, identifies the hot task classes, and recompiles their parameter sets through canary experiments, while production traffic keeps flowing.
That constraint shaped the whole design. NoeticOS never explores on baseline traffic: exploration is confined to a deterministic canary cohort, 10% of executions by default, and a canary differs from the baseline in exactly one parameter at a time. Promotion requires statistical confidence, rollback fires on much weaker evidence by design, and a hard quality floor rolls back any violating canary regardless of reward. Every change lands in an append-only audit log with the numbers that justified it.
Promotion uses Welch's t test on mean reward, with the alpha spread across a Bonferroni look budget, plus confidence-bound separation: the candidate's lower bound must clear the baseline's upper bound. Rollback uses an exact binomial test on failure counts, a Wilson score upper bound checked against the quality floor, and a futility bound that abandons a canary after four times the minimum sample budget without a verdict.
No. The prompt is an optional classifier input and is never stored: snapshots, decisions, and telemetry carry aggregate statistics only. The OTel ingestion deliberately ignores span events, which can carry message bodies, and tool-call arguments enter only as caller-computed hashes.
Zero. The core is 11.15 kB brotli and uses nothing beyond the JavaScript standard library; the statistics (Welch, Wilson, exact binomial, P2 quantile estimators) are implemented inside the package. The family bridges are structural, so even the optional peer packages are never imported by the engine itself.
Yes. The web and edge entry points (10.54 kB brotli each) expose the full engine minus the Node file
backend, so bundles never reference node:fs. Cohort assignment uses a seeded deterministic
PRNG, not platform randomness, so the same configuration behaves identically in Node, Cloudflare
Workers, Vercel Edge, Deno, Bun, and the browser.
@takk/noeticos/vercel ships a packaged middleware for wrapLanguageModel: it
applies the recommended temperature and topP per call and reports token usage, latency, and finish
reason automatically, for generateText and streamText alike.
@takk/noeticos/otel converts OTel GenAI semantic-convention spans into task descriptors
and outcomes structurally, without importing any OpenTelemetry package; ingestion is live by design,
and replaying exported traces warms the cost and latency quantile bands rather than performing
historical credit assignment.
159 tests across 12 files run on Node 22 and Node 24, with 92.15% line coverage. A 9-scenario tuning benchmark runs in CI, so a change that stops the engine from beating a static baseline fails the build. Bundle size budgets are enforced per entry point, and every release is published with SLSA provenance through GitHub Actions OIDC.
Strict SemVer 2.0.0 from 1.0.0. Everything exported from the six entry points is the public API, the
state snapshot schema is versioned (version 1 across the 1.x line), and new task kinds may be added in
minor releases, so exhaustive switches over TaskKind should keep a default branch.
Breaking changes require a major bump and a deprecation cycle.