Chronicle: Self-Serve Finetuning Guide

:::info Preview feature Chronicle self-serve finetuning is rolling out to allowlisted accounts. The Finetuning page appears in your dashboard once your account is enabled. :::

Chronicle — InertialAI's self-serve finetuning product — lets you adapt an InertialAI foundation model to your own real-world data (sensor streams, metrics, health signals, market series) and deploy it behind a private endpoint — no calls, no contracts, no waiting on our team. The whole journey runs from your dashboard:

1. Pick a base model — chronicle, inertialai-forecast, or inertialai-embed.
2. Upload a dataset in the fixed JSONL schema below. Each record's input may contain text, a time series, or both.
3. Get a quote and pay. Training is a per-job base fee plus a data-volume fee, and your quote is frozen at payment time.
4. Training runs automatically and finishes with a before/after eval: your tuned model versus the frozen base on a held-out split. If the tuned model doesn't beat the base, the training fee is automatically refunded.
5. Choose serving compute (GPU type, scaling, latency mode) and launch. You pay for GPU time — metered per call (cold-start included), plus hourly for any always-warm replicas — with a spend cap that suspends the endpoint before costs can run away.

Two dashboard companions round the journey out:

• Data Explorer — upload a file and see, before paying anything, what it contains, which models it can finetune, under which objective, and the exact training price (LoRA and full). It runs the same validator as the wizard, so a green verdict there is a green verdict here.
• Sandbox → My models — query any of your live deployments with manual data straight from the browser; the result view follows the training objective (forecast fan, generated text, label, values, or an embedding).

Base models

Model	Kind	Training target	Serving
chronicle	The multimodal foundation model (text + time-series)	output.series (and/or output.text)	POST /v1/endpoints/{id}/predict
inertialai-forecast	The production forecasting model (quantile objective only)	output.series	POST /v1/endpoints/{id}/predict, or POST /v1/forecasts with forecaster
inertialai-embed	Embedding model (GA)	Label, positive/negative pairs, or unsupervised multi-modal	POST /v1/endpoints/{id}/embed

Deploying a base model without training

If all you want is a dedicated endpoint — your own GPU, your own spend cap, a private deployment name — you can deploy any base model as-is, with no training step and no training fee:

deployment = client.deployments.create_base("forecast", name="my-forecaster")

or POST /v1/endpoints with base_model instead of job_id (the dashboard has a "Deploy a base model" button). The endpoint serves the untrained base model and bills GPU time exactly like a tuned deployment. A base inertialai-forecast deployment can also be named as the forecaster on POST /v1/forecasts, so reasoning mode runs on your dedicated GPU. When you later finetune, promote the job onto the same deployment name — the base version stays in the history for rollback.

inertialai-forecast and inertialai-embed are built for this. Deploying chronicle untrained is allowed but not recommended: its value is in what it finetunes into.

Dataset format

Upload JSONL (one JSON object per line), or a ZIP of JSONL shards for datasets over the single-file limit (2 GiB by default).

Chronicle records

{
  "input": {
    "text": "Promo launched; regional heatwave forecast.",
    "series": {
      "timestamps": ["2026-01-01T00:00:00Z", "2026-01-01T01:00:00Z"],
      "values": [12.4, 13.1],
      "freq": "1h"
    }
  },
  "output": {
    "series": {
      "timestamps": ["2026-01-01T02:00:00Z"],
      "values": [14.0]
    }
  }
}

• input must contain text, series, or both; forecasting models require output.series.
• timestamps and values must be equal length; timestamps are ISO-8601 and strictly increasing; freq is optional but checked against the spacing.
• Multivariate series: make values an array of arrays and add a sibling channels: ["temp", "load"]. The channel count must be consistent across the whole file.

InertialAI-EMBED records

Three modes; the file declares its mode with the first record and must be homogeneous.

Labeled (classification-style adaptation):

{ "input": { "series": { "...": "..." } }, "output": { "label": "anomaly" } }

Pairs (contrastive/retrieval adaptation):

{ "anchor": { "series": { "...": "..." } }, "positive": { "text": "..." }, "negatives": [{ "text": "..." }] }

Unsupervised (multi-modal domain adaptation — no labels needed): records contain only input, with both text and series. The two modalities of each record form a natural pair, so the embedding space is aligned to your domain with zero annotation effort:

{ "input": { "text": "driver swing, fast tempo", "series": { "...": "..." } } }

Validation

Every upload is fully validated before you can pay. Fatal errors (malformed JSON, missing fields, modality violations, length mismatches, non-monotonic timestamps, mixed EMBED modes) block the job; warnings (short series, missing values, class imbalance, near-duplicates) do not. The report also meters your dataset — records, series points, text tokens — which is exactly what the quote is computed from.

How finetuning works (and what "base" means)

Every model family finetunes the real production weights through one centralized trainer:

• inertialai-forecast — the production forecasting system is a mixture-of-experts router over frozen foundation forecasters. Finetuning trains that router on your series (masked, scale-normalised quantile loss); the foundation experts stay frozen and their forecasts are precomputed, which is what keeps training fast. At epoch 0 the router equals the calibrated expert ensemble — training is learning how to route and correct for your data.
• chronicle — the released Chronicle checkpoint itself trains, with LoRA (real low-rank adapters on the attention/MLP weights — the default, 75% off) or a full finetune (every weight, listed rate). The chronicle_stage knob picks the pretraining stage to start from (stage 2, the long-context checkpoint, is the default). Series targets use the model's own masked quantile loss; text targets train next-token cross-entropy; classification/regression train a new head over the pooled hidden state.
• inertialai-embed — the production embedding backbone stays frozen and a residual projection head trains on top with real contrastive / prototype objectives.

A bad finetune can never damage a base capability: base weights are shared, immutable inputs; your tuned weights live in your account's isolated storage.

Input and output are configured entirely by your dataset and the request, not by knobs: the modalities your records contain define what the tuned model accepts, the output field defines what it produces (forecast horizon and values for Chronicle, vectors for EMBED), and at inference time options.horizon / options.return_text shape the response.

Training knobs. Start from a preset (quick / standard / thorough) or override any of these per job:

Knob	Range	Default
epochs	1 – 200	preset (5 / 20 / 60)
learning_rate	1e-5 – 1.0	preset (3e-3 / 1e-3 / 3e-4)
optimizer	adamw, adam, sgd	adamw
batch_size	1 – 1024	32
weight_decay	0 – 1	0.01
scheduler	cosine, constant	cosine
grad_clip	0 – 100	1.0
lora_rank	1 – 64	8
holdout_fraction (train/val split)	5% – 50%	10%
loss (classification/regression only)	mse, mae, huber	mse
early_stopping / early_stop_patience	bool / 1 – 50	off / 5
seed	any	13
chronicle_stage (chronicle only)	1, 2	2

Series targets always train the quantile objective (pinball loss on the canonical 0.1–0.9 grid, served as a quantile fan) and text targets always train cross-entropy — see the training reference for the full objective matrix and the special-token codec for joint outputs.

You can also upload a separate validation file (same format and dataset mode as the training file). It replaces the random split: every training record trains, and your validation set drives both the loss curves and the before/after eval.

Training curves. Every job stores its measured per-epoch train and validation loss under the selected loss function; the dashboard plots the curves in the training step and the job detail view, so overfitting and under-training are visible at a glance.

"Base" in every eval is that frozen base model, run on the exact same held-out records as your tuned model. When you see "+91% vs base", it means the tuned adapter reduced forecast error (NMAE) by 91% relative to what the frozen base model achieves on data it has never seen — the like-for-like comparison that tells you the finetune was worth it.

The before/after eval

Every finetune holds out a split of your data (10% by default) and compares the tuned model against the frozen base on it — NMAE for forecasting models, classification accuracy or retrieval recall for embeddings. The eval report is shown before you commit to serving. If the tuned model doesn't beat the base beyond a small threshold, the job is flagged and your training fee is automatically refunded.

Inference contract

Endpoints share a fixed contract behind your InertialAI API key — the same modality rules as training, and a usage block on every response:

POST /api/v1/endpoints/{endpoint_id}/predict
{
  "input": { "series": { "timestamps": ["..."], "values": [1.0], "freq": "1h" } },
  "options": { "horizon": 24, "return_text": true }
}

{
  "output": { "series": { "timestamps": ["..."], "values": [1.0] }, "text": "..." },
  "model": "chronicle:ft-<id>",
  "usage": { "series_points_in": 168, "series_points_out": 24, "text_tokens": 40, "compute_cents": 1 }
}

Embedding endpoints return { "embedding": [...], "dim": 768, "model": "inertialai-embed:ft-<id>", "usage": { ... } }.

Reasoning mode on your endpoint

Any quantile-capable deployment — a finetuned forecaster, a finetuned Chronicle, or a base-model deployment — can run reasoning mode directly on its own predict route. It is the same Stage-2 LLM layer the hosted reasoning model uses, wrapped around your model's forecast: supply context (or set options.reasoning: true, or pick an options.reasoning_model from the reasoning model catalog):

POST /api/v1/endpoints/{endpoint_id}/predict
{
  "input": { "series": { "timestamps": ["..."], "values": [1.0], "freq": "1h" } },
  "context": "A promotion starts tomorrow; expected demand lift ~20%.",
  "options": { "horizon": 24, "reasoning_model": "mistralai/mistral-small-3.2-24b-instruct" }
}

The response's forecast is the adjusted fan, plus a reasoning block with the status (applied, or unavailable when the LLM provider failed — the forecast is then series-calibrated only and the reasoning leg is not charged), the model used, its rationale, and the applied adjustments. The LLM leg bills exactly like hosted reasoning, on top of your endpoint's GPU time. POST /v1/forecasts with forecaster: <endpoint> remains available and returns the richer forecast-API response shape.

Where your models live

Tuned weights are written to isolated, per-customer storage on the training infrastructure (a dedicated storage prefix that only your jobs and your endpoints mount). They are stored free of charge for as long as the finetune exists — there is no storage fee and no automatic expiry today. Raw dataset uploads, by contrast, are deleted automatically when training completes unless you opt into retention. DELETE /v1/finetune/data (or the dashboard action) hard-deletes everything at any time. Details in the Finetuning Data Policy.

Cost safety

• Serving compute is metered per call: the measured runtime of each call at the published GPU hourly rate. Scale-to-zero endpoints cost nothing while idle.
• Every endpoint has a spend cap. At 80% you're alerted; at 100% the endpoint suspends until you raise the cap and relaunch.
• One deployment per account. A live (even scaled-to-zero) or suspended deployment holds your account's single deployment slot; terminate it to launch another. Tuned weights always stay stored, so a terminated deployment can be redeployed at any time — this bound is what keeps per-account serving storage flat and endpoints cheap.

See also: the Finetuning Training Reference for exactly how objectives are chosen and what every constraint is, Finetuning Pricing for the full price list, and the Finetuning Data Policy for how your uploads, weights, and eval artifacts are stored and deleted.