c3aiia3c
/

CHARM

@@ -6,759 +6,151 @@ tags:
   - foundation-model
   - zero-shot
   - gift-eval
 pipeline_tag: time-series-forecasting
 library_name: pytorch
 ---
 # CHARM
-CHARM is a zero-shot probabilistic time-series foundation model from **C3 AI**.
-It produces full quantile forecasts (99 quantile levels) for arbitrary horizons and
-is evaluated zero-shot on the [GIFT-Eval](https://huggingface.co/spaces/Salesforce/GIFT-Eval)
-benchmark — no GIFT-Eval data is used in training.
-> **Availability:** CHARM model weights and training/replication code are
-> **not publicly released**. The model is served behind an API and consumed
-> through the open-source **`c3-charm` Python SDK** (see [Using CHARM](#using-charm--the-c3-charm-sdk) below).
-> This page serves as the model card and benchmark record.
-## Model summary
-| | |
-|---|---|
-| Parameters | ~63.3M (encoder ~59M) |
-| Hidden size (d_model) | 384 |
-| Projection | TCN-pool (patch size 16, causal conv stack + residual gate) |
-| Backbone | Transformer encoder with RoPE attention |
-| Decoder | Quantile decoder, 99 levels (0.01–0.99) |
-| Max context length | 8192 |
-| Output | Probabilistic (quantile) forecasts, multivariate-capable |
-| Precision | float32 |
-## Intended use
-Zero-shot probabilistic forecasting of univariate and multivariate time series
-across domains (energy, transport, sales, healthcare, nature, web/cloud-ops,
-econ/finance). The model is applied without any per-dataset fine-tuning.
-## Using CHARM — the `c3-charm` SDK
-CHARM is served behind an API and consumed through the open-source [`c3-charm`](https://pypi.org/project/c3-charm/) Python SDK. The SDK provides **embeddings** (multivariate time series → vectors), **forecast/backcast** (quantile predictions), and an optional **toolkit** for downstream tasks (anomaly detection, retrieval, classification, reconstruction, forecasting). The reference below is the full SDK documentation.
-> **Dual-model serving.** A CHARM server can be backed by two independent checkpoints — one for embeddings (`/predict`, `client.embeddings`) and a separate one for forecasting (`/forecast`, `client.prediction`). They may differ in architecture, patch size, and embedding dimension, so read per-model properties from `client.model_info()` rather than hardcoding.
-### Example notebooks
-Runnable notebooks live in [`notebooks/`](./notebooks) in this repo. Open them on the Hub, or download the folder and run locally after `pip install c3-charm[toolkit]` (set `CHARM_BASE_URL` / `CHARM_API_KEY` first). The classification and reconstruction/forecasting demos read the small sample datasets in [`notebooks/data/`](./notebooks/data).
-| Notebook | What it covers |
-|---|---|
-| [`getting_started.ipynb`](./notebooks/getting_started.ipynb) | Client setup, first embeddings call, inspecting `model_info()`. |
-| [`charm_toolkit_demo.ipynb`](./notebooks/charm_toolkit_demo.ipynb) | Tour of the `charm_toolkit` — datasets, precompute, trainer, and each task head. |
-| [`demo_forecasting.ipynb`](./notebooks/demo_forecasting.ipynb) | Zero-shot quantile forecasting and the embedding-based `ForecastingModel` head (weather data). |
-| [`demo_reconstruction.ipynb`](./notebooks/demo_reconstruction.ipynb) | Backcast reconstruction and the `ReconstructionModel` head for anomaly detection (weather data). |
-| [`demo_classification.ipynb`](./notebooks/demo_classification.ipynb) | Time-series classification with the `ClassificationModel` head (BasicMotions data). |
-| [`demo_retrieval_anomaly_detection.ipynb`](./notebooks/demo_retrieval_anomaly_detection.ipynb) | Embedding retrieval + kNN / zero-shot anomaly-detection recipes. |
-### Installation
 ```bash
-pip install c3-charm            # core SDK only (embeddings + forecast)
-pip install c3-charm[toolkit]   # includes PyTorch models, datasets, trainers
 ```
-Or from source:
-```bash
-git clone https://github.com/c3ai/c3-charm.git
-cd c3-charm
-poetry install                    # core SDK only
-poetry install --with toolkit     # include toolkit dependencies
-```
-#### CPU vs CUDA torch
-`pip install c3-charm` pulls the **default torch wheel from PyPI**, which on
-Linux is the full **CUDA** build (~4 GB). The SDK itself never requires a
-GPU — the model runs server-side, and toolkit training heads are small
-enough to fit on CPU — so if you want the smaller CPU-only wheel, install
-torch from the CPU index **before** `c3-charm`:
-```bash
-pip install torch --index-url https://download.pytorch.org/whl/cpu
-pip install c3-charm
-```
-Or from source, use `bash setup.sh`, which forces the CPU wheel.
-If you instead want a specific CUDA build, install it manually **after**
-`c3-charm`:
 ```bash
-pip install --force-reinstall --no-deps torch \
-    --index-url https://download.pytorch.org/whl/cu124
-```
-Swap `cu124` for the CUDA version that matches your driver (`cu121`,
-`cu126`, `cu128`, …). `--no-deps` is important — it stops pip from
-re-resolving your torch install.
----
-### Core SDK
-#### Client initialization
-```python
-from charm import CharmClient
-client = CharmClient(
-    base_url="http://your-server:8080",
-    api_key="your-api-key",      # or set CHARM_API_KEY env var
-    timeout=300,                 # override; SDK default is 15s — raise it for /forecast (server allows up to ~220s)
-    max_retries=3,
-)
-```
-#### Embeddings — `client.embeddings.create()`
-Converts time series windows into dense vectors.
-```python
-response = client.embeddings.create(
-    descriptions=[["sensor_A", "sensor_B"]],  # (N, C) channel names
-    ts_array=[[[1.0, 2.0], [1.1, 2.1], ...]],  # (N, T, C) values
-    batch_size=32,
-    return_tensors="np",       # "list", "np", or "torch"
-    aggregate=True,            # True → (N, D); False → (N, T_, C, D)
-    progress=True,
-)
-embeddings = response.embeds  # shape (N, D) when aggregate=True
-```
-**`aggregate` parameter:**
-- `True` (default): Returns flattened embeddings `(N, D)` — one vector per series. Best for retrieval, classification, clustering.
-- `False`: Returns per-patch, per-channel embeddings `(N, T_, C, D)` where `T_ = ceil(T / patch_size)`. Best for fine-grained tasks or custom heads.
-**Async** (faster for large datasets):
-```python
-response = await client.embeddings.async_create(
-    descriptions=descriptions,
-    ts_array=ts_array,
-    max_B_per_request=32,
-    concurrency_per_call=8,
-    return_tensors="np",
-    aggregate=True,
-)
-```
-#### Forecast / Backcast — `client.prediction.create()`
-Zero-shot quantile predictions — no training required.
-```python
-response = client.prediction.create(
-    descriptions=[["sensor_A", "sensor_B"]],
-    ts_array=[[[1.0, 2.0], [1.1, 2.1], ...]],
-    target_len=10,       # positive = forecast, negative = backcast
-    return_tensors="np",
-)
-forecast = response.denormalized_predictions  # (N, target_len=10, C, Q) — Q quantiles (model-dependent, e.g. 21)
-median = response.median                      # (N, 10, C) — point forecast (median quantile)
-```
-**Backcast** (reconstruct past values):
-```python
-response = client.prediction.create(
-    descriptions=descriptions,
-    ts_array=ts_array,
-    target_len=-8,  # reconstruct last 8 steps
-    return_tensors="np",
-)
-```
-#### Input constraints
-| Constraint | Limit |
-|---|---|
-| Timesteps per series | 1 ≤ T ≤ 8192 (the model's training window) |
-| Channels per series | No hard limit (large C grows memory ~O(C²) under cross-channel attention) |
-| Per-request size | N × C × T ≤ 500,000 — SDK client-side batching guard, not a server limit |
-| Batch consistency | All series in a request must share the same T and C |
-| Best accuracy | T ≤ 8192 (the model's training window); T need not be a multiple of the patch size |
-The model was trained on windows of up to 8192 timesteps (patch size 16).
-Inputs are not required to be a multiple of the patch size — they are padded
-to a patch boundary internally. The architecture can technically accept more
-than 8192 (up to 1500 patches), but longer inputs rely on positions seen only
-in pretraining, so quality degrades. Query `client.model_info()` for the
-served model's actual patch size and embedding dimension.
-The SDK handles client-side batching automatically when you set `batch_size` (sync) or `max_B_per_request` (async).
-#### Output shapes
-| Method | Output field | Shape |
-|---|---|---|
-| `embeddings.create(aggregate=True)` | `response.embeds` | (N, D) |
-| `embeddings.create(aggregate=False)` | `response.embeds` | (N, T_, C, D), T_ = ceil(T / patch_size) |
-| `prediction.create(target_len > 0)` | `response.denormalized_predictions` | (N, target_len, C, Q) |
-| `prediction.create(target_len < 0)` | `response.denormalized_predictions` | (N, abs(target_len), C, Q) |
-| `prediction.create(...)` | `response.median` | (N, abs(target_len), C) |
-#### Channel descriptions
-Descriptions are **required** and affect embedding quality. They tell the model what each channel represents.
-**Good descriptions** — use meaningful, consistent names:
-```python
-descriptions = [["engine_temperature", "oil_pressure", "rpm"]]
-```
-**Acceptable** — short but informative:
-```python
-descriptions = [["temp", "pressure", "speed"]]
-```
-**Avoid** — generic or positional names reduce model effectiveness:
-```python
-descriptions = [["col_0", "col_1", "col_2"]]  # works but suboptimal
-```
-When working with pandas DataFrames, use column names directly:
-```python
-descriptions = [df.columns.tolist()] * N
-```
-#### Scaling
-**No pre-processing needed.** CHARM normalizes internally. Send raw data as-is. Do not apply StandardScaler, MinMaxScaler, or log transforms before calling the API.
-#### Error handling
-```python
-from charm import CharmError, AuthenticationError, InvalidRequestError, RateLimitError
-try:
-    response = client.embeddings.create(...)
-except AuthenticationError:
-    # bad API key
-except InvalidRequestError as e:
-    # shape violations, empty input
-except RateLimitError:
-    # back off and retry
-except CharmError as e:
-    # catch-all for other SDK errors
-```
----
-### Toolkit — Downstream Tasks
-The toolkit (`pip install c3-charm[toolkit]`) provides PyTorch models, dataset utilities, and training infrastructure for fine-tuning on top of CHARM embeddings.
-#### Retrieval — `charm_toolkit.retrieval`
-Find similar time series by embedding similarity.
-```python
-from charm_toolkit.retrieval import (
-    l2_normalize,
-    cosine_similarity_matrix,
-    knn_search,
-    retrieval_metrics,
-)
-# Embed your data
-response = client.embeddings.create(
-    descriptions=descriptions,
-    ts_array=windows_list,
-    return_tensors="np",
-)
-embeddings = response.embeds  # (N, D)
-# Similarity search
-sim = cosine_similarity_matrix(embeddings, embeddings)
-# kNN search
-indices, scores = knn_search(query_emb, corpus_emb, k=5)
-# Evaluation metrics
-metrics = retrieval_metrics(
-    query_emb=query_emb,
-    corpus_emb=corpus_emb,
-    query_labels=query_labels,
-    corpus_labels=corpus_labels,
-    k_values=[1, 3, 5, 10],
-    exclude_self=True,
-    query_ids=query_dataset_names,
-    corpus_ids=corpus_dataset_names,
-)
-# Returns: precision@k, ndcg@k, hit_rate@k
-```
-#### Anomaly Detection — `charm_toolkit.anomaly_detection`
-Detect anomalies via kNN distance scoring on windowed CHARM embeddings.
-```python
-from charm_toolkit.anomaly_detection import (
-    sliding_window_embeddings,
-    knn_anomaly_scores,
-    window_scores_to_pointwise,
-)
-# 1. Embed sliding windows
-train_emb = sliding_window_embeddings(
-    client, train_data, descriptions,
-    window_size=128, stride=1, batch_size=64,
-)
-test_emb = sliding_window_embeddings(
-    client, test_data, descriptions,
-    window_size=128, stride=1, batch_size=64,
-)
-# 2. Score test windows by distance to train
-window_scores = knn_anomaly_scores(
-    test_emb=test_emb,
-    reference_emb=train_emb,
-    k=5,
-    distance="cosine",    # "cosine", "l2", "l1"
-    aggregation="mean",   # "mean", "max"
-)
-# 3. Aggregate to per-timestep scores
-pointwise_scores = window_scores_to_pointwise(
-    window_scores=window_scores,
-    window_size=128,
-    stride=1,
-    total_length=len(test_data),
-    method="mean",  # "mean", "max", "last", "center"
-)
 ```
-**Pointwise aggregation methods:**
-Each timestep is covered by multiple overlapping windows. The `method` parameter controls how to assign a single score per timestep:
-| Method | Behavior | Use case |
-|--------|----------|----------|
-| `"mean"` | Average of all windows covering the point | Smooth, best for offline evaluation |
-| `"max"` | Max score among covering windows | Conservative, catches isolated spikes |
-| `"last"` | Score of the most recently *completed* window | Online/streaming — score only updates when a window finishes processing |
-| `"center"` | Score of the window centered on each point | Minimal time-shift, tightest temporal alignment |
-**Zero-shot recipes (no clean reference set required) — recommended methods, in order of strength:**
-1. **Bootstrap k-NN** (best). Two steps: run `sklearn.ensemble.IsolationForest` on the embedding matrix and take the bottom ~70% by score as a presumed-clean reference; then call `knn_anomaly_scores` against that reference.
-2. **CBLOF**: `pyod.models.cblof.CBLOF` on the embedding matrix.
-3. **IsolationForest**: `sklearn.ensemble.IsolationForest` directly on the embedding matrix.
-L2-normalize embeddings beforehand to use cosine geometry. See `demo_retrieval_anomaly_detection.ipynb`.
-**Best practices (validated on TSB-AD, metric VUS-PR):**
-1. **Ensemble the embedding score with per-window statistics.** The encoder
-   instance-normalizes each window, erasing amplitude/level-shift anomalies (spikes,
-   steps — the most common kind) from the embedding. Recover them with
-   `window_statistics` (no extra model call) and combine via `ensemble_scores`
-   (`method="zscore"` — z-score each detector and sum; parameter-free and as strong as a
-   tuned weighted ensemble). This is worth **~+7 pp VUS-PR** supervised.
-   ```python
-   from charm_toolkit.anomaly_detection import window_statistics, ensemble_scores
-   emb_score = knn_anomaly_scores(test_emb, train_emb, k=3, distance="cosine")
-   S_tr = window_statistics(train_data, 128, 1)
-   mu, sd = S_tr.mean(0, keepdims=True), S_tr.std(0, keepdims=True) + 1e-8
-   stats_score = knn_anomaly_scores(
-       (window_statistics(test_data, 128, 1) - mu) / sd, (S_tr - mu) / sd,
-       k=3, distance="l2")
-   window_scores = ensemble_scores([emb_score, stats_score], method="zscore")
-   # zero-shot: build the reference by bootstrap (above) and use method="rank"
-   ```
-2. **Multivariate: do NOT pool channels when the channel count is high.** Channel-mean
-   pooling dilutes an anomaly confined to a few channels across all of them. Keep channels
-   separate with `sliding_window_channel_embeddings` + `per_channel_knn_scores`
-   (`channel_pool="adaptive"`). The benefit grows with the number of channels — negligible
-   at C≤3, sizeable at C≥20, large at C>60 — so it is **advisable whenever C is high**. For
-   few channels, plain mean-pooling is equally good and cheaper.
-   ```python
-   from charm_toolkit.anomaly_detection import (
-       sliding_window_channel_embeddings, per_channel_knn_scores)
-   train_pc = sliding_window_channel_embeddings(client, train_data, descriptions)  # (N, C, D)
-   test_pc  = sliding_window_channel_embeddings(client, test_data, descriptions)
-   emb_score = per_channel_knn_scores(test_pc, train_pc, k=3, channel_pool="adaptive")
-   ```
-#### ReconstructionModel — anomaly detection via learned head
-```python
-from charm_toolkit import (
-    ReconstructionModel, create_reconstruction_datasets,
-    collator, TrainerClass,
-)
-from torch.utils.data import DataLoader
-import torch.nn as nn
-train_ds, val_ds, test_ds = create_reconstruction_datasets(
-    raw_data,           # (T, C) numpy array or torch tensor
-    descriptions=channel_names,
-    window_size=256,
-    stride=1,
-    train_ratio=0.7,
-    val_ratio=0.15,
-    sequential=True,
-    scale=True,
-)
-model = ReconstructionModel(
-    embedding_client=client,
-    reconstructor="linear",  # "linear", "mlp", or custom nn.Module
-    hidden_dim=128,
-    dropout=0.1,
-)
-trainer = TrainerClass(
-    model=model,
-    train_loader=DataLoader(train_ds, batch_size=512, collate_fn=collator),
-    val_loader=DataLoader(val_ds, batch_size=512, collate_fn=collator),
-    epochs=1000,
-    patience=5,
-    lr=1e-3,
-    criterion=nn.HuberLoss(),
-)
-trainer.fit()
-```
-#### ForecastingModel — embedding-based forecasting
-```python
-from charm_toolkit import ForecastingModel, create_forecasting_datasets, collator, TrainerClass
-from torch.utils.data import DataLoader
-train_ds, val_ds, test_ds = create_forecasting_datasets(
-    raw_data,
-    descriptions=channel_names,
-    train_horizon=96,
-    test_horizon=96,
-    train_ratio=0.7,
-    val_ratio=0.15,
-    sequential=True,
-    scale=True,
-)
-model = ForecastingModel(
-    embedding_client=client,
-    horizon=96,
-    input_size=96,
-    head="linear",
-    hidden_dim=128,
-    mode="last",         # "last", "avg", "none"
-    per_channel=True,
-    num_channels=len(channel_names),
-)
-trainer = TrainerClass(
-    model=model,
-    train_loader=DataLoader(train_ds, batch_size=512, collate_fn=collator),
-    val_loader=DataLoader(val_ds, batch_size=512, collate_fn=collator),
-    epochs=1000,
-    patience=10,
-    lr=1e-2,
-)
-trainer.fit()
-```
-#### ClassificationModel — time series classification
-```python
-from charm_toolkit import ClassificationModel, create_classification_datasets, collator, TrainerClass
-from torch.utils.data import DataLoader
-import torch.nn as nn
-train_ds, val_ds, test_ds = create_classification_datasets(
-    raw_data,          # (N, T, C)
-    labels=labels,     # list of N integer labels
-    descriptions=channel_names,
-    train_ratio=0.7,
-    val_ratio=0.15,
-)
-model = ClassificationModel(
-    embedding_client=client,
-    num_classes=num_classes,
-    hidden_dim=128,
-    pooling_over_t="mean",
-    pooling_over_channels="mean",
-    classifier_type="mlp",
-)
-trainer = TrainerClass(
-    model=model,
-    train_loader=DataLoader(train_ds, batch_size=32, collate_fn=collator),
-    val_loader=DataLoader(val_ds, batch_size=32, collate_fn=collator),
-    epochs=100,
-    patience=10,
-    lr=1e-3,
-    criterion=nn.CrossEntropyLoss(),
-)
-trainer.fit()
-```
-#### Precomputing embeddings (critical for training)
-Toolkit models call the API every forward pass. For training with hundreds of windows per epoch, **precompute embeddings once**:
-```python
-from charm_toolkit import precompute_dataset_embeddings, PrecomputedEmbeddingsDataset
-# Compute once, save to disk as memmap
-train_shape = precompute_dataset_embeddings(
-    client=client, dataset=train_ds,
-    output_path="./outputs/train_embeddings.pt", memory_batch_size=8192
-)
-val_shape = precompute_dataset_embeddings(
-    client=client, dataset=val_ds,
-    output_path="./outputs/val_embeddings.pt", memory_batch_size=8192
-)
-# Wrap datasets — model skips API calls when "embeds" key present
-train_ds = PrecomputedEmbeddingsDataset(train_ds, "./outputs/train_embeddings.pt", train_shape)
-val_ds = PrecomputedEmbeddingsDataset(val_ds, "./outputs/val_embeddings.pt", val_shape)
-# Training now uses cached embeddings — orders of magnitude faster
-train_loader = DataLoader(train_ds, batch_size=512, shuffle=True, collate_fn=collator)
-```
-#### Trainer API
-```python
-from charm_toolkit import TrainerClass
-trainer = TrainerClass(
-    model=model,
-    train_loader=train_loader,
-    val_loader=val_loader,
-    test_loader=test_loader,     # optional
-    lr=1e-3,
-    weight_decay=1e-4,
-    epochs=1000,
-    patience=5,
-    min_delta=1e-4,
-    max_grad_norm=5.0,
-    criterion=None,              # defaults to MSELoss
-)
-trainer.fit()
-test_loss = trainer.evaluate(test_loader)
-```
-#### Dataset factory functions
-All return `(train_dataset, val_dataset, test_dataset)`:
-| Function | Input shape | Key args |
-|---|---|---|
-| `create_reconstruction_datasets(raw_data, ...)` | (T, C) | `window_size`, `stride`, `train_ratio`, `val_ratio` |
-| `create_forecasting_datasets(raw_data, ...)` | (T, C) | `train_horizon`, `test_horizon`, `stride`, `train_ratio`, `val_ratio` |
-| `create_classification_datasets(raw_data, labels, ...)` | (N, T, C) | `train_ratio`, `val_ratio` |
-Reconstruction and forecasting expect a single long time series `(T, C)` split temporally. Classification expects pre-windowed `(N, T, C)`.
-#### collator
-All DataLoaders using toolkit datasets require `collator` as the `collate_fn`:
-```python
-from charm_toolkit import collator
-# or equivalently:
-from charm_toolkit.Datasets import collator
-```
----
-### Embeddings as features
-CHARM embeddings work as drop-in feature vectors for any sklearn model:
-```python
-import numpy as np
-from sklearn.ensemble import IsolationForest
-from sklearn.linear_model import LogisticRegression
-from charm_toolkit.retrieval import cosine_similarity_matrix
-response = client.embeddings.create(
-    descriptions=descriptions,
-    ts_array=windows_list,
-    return_tensors="np",
-)
-X = response.embeds  # (N, D)
-# Anomaly detection with isolation forest
-clf = IsolationForest(contamination=0.05)
-anomaly_labels = clf.fit_predict(X)
-# Similarity search
-sim = cosine_similarity_matrix(X, X)
-# As features for any classifier
-clf = LogisticRegression().fit(X_train, y_train)
-```
----
-### Local Deployment
-Deploy models locally from GitHub releases — no remote server needed:
-```python
-with CharmClient(tag="experiment-2026-03-15_10-30-00") as client:
-    response = client.embeddings.create(...)
-# Server shuts down automatically
-```
-When `tag` is provided:
-1. Checks for GPU availability (falls back to CPU)
-2. Clones repo at the specified tag (shallow clone)
-3. Downloads model weights from the GitHub release
-4. Launches the serving stack locally
-5. Polls health endpoint until ready
-Files cached at `~/.charm/models/<tag>/` for fast subsequent runs.
-```python
-CharmClient(
-    tag="experiment-tag",           # required for local mode
-    repo_url="https://...",         # default: c3-e/research
-    cache_dir="/path/to/cache",     # default: ~/.charm/models
-    port=8080,                      # 0 = auto-select
-)
-```
----
-### Best practices
-#### Input & preprocessing
-- Send data as `(N, T, C)` — N series, each T timesteps × C channels; all series in one request must share the same T and C.
-- Keep `T ≤ 8192` (the training window). The model can accept more, but quality degrades on lengths it wasn't trained on. T does **not** need to be a multiple of the patch size — inputs are padded to a patch boundary internally.
-- **Do not pre-scale** your data. CHARM normalizes internally (asinh z-score); applying StandardScaler/MinMaxScaler/log yourself hurts results.
-#### Channel descriptions (a real quality lever)
-- Use meaningful, consistent channel names (`"engine_temperature"`, not `"col_0"`) — the model is channel-aware and descriptions materially affect embeddings.
-- Reuse the same names across requests so embeddings stay comparable (retrieval, clustering).
-#### Batching & throughput
-- Respect the per-request budget: `batch_size × C × T ≤ 500,000` (SDK-enforced client-side).
-- Use `async_create` for large N — it batches concurrently; the sync client is sequential and slow past ~100 series. Tune `max_B_per_request` / `concurrency_per_call` instead of one giant request.
-#### Timeouts & retries
-- Raise `timeout` for forecasting — the SDK default is 15s, but the server allows forecasts up to ~220s. Use `timeout ≈ 220+` for `prediction.create`.
-- Keep the built-in retries (exponential backoff on 429/5xx) rather than hand-rolling.
-#### Embeddings
-- `aggregate=True` (default) → `(N, D)` for retrieval / classification / clustering. `aggregate=False` → `(N, T_, C, D)` only when you need per-patch/per-channel detail for a custom head.
-- L2-normalize before cosine similarity (embeddings are unit-normed by the encoder, but normalize again after any pooling you do).
-- Discover `D` at runtime via `client.model_info()` — it's model-dependent; don't hardcode.
-#### Forecasting
-- `target_len > 0` = forecast, `< 0` = backcast; `0` is invalid.
-- Keep `T + abs(target_len) ≤ 8192` (the training window) for best forecast/backcast quality.
-- Use `response.median` for a point forecast, or the full quantile axis for intervals. `Q` is model-dependent (e.g. 21 or 99) — read `denormalized_predictions.shape[-1]`.
-#### Classification
-- For classification heads, **don't pool over channels** — keeping the per-channel embeddings flat (rather than averaging them) boosts accuracy, at a modest cost in head size/complexity. In the toolkit `ClassificationModel`, set `pooling_over_channels="flatten"` (and pass `num_channels=C`, required for flatten) instead of the default `"mean"`.
-#### Dual-model awareness
-- Treat `/predict` (embeddings) and `/forecast` as **separate models** — they may have different patch sizes / embedding dims. Read the per-role `models` map from `client.model_info()` instead of assuming they match.
-#### Training on top of CHARM
-- Precompute embeddings once (`precompute_dataset_embeddings` + `PrecomputedEmbeddingsDataset`) — toolkit models otherwise call the API every forward pass.
-#### Reliability & ops
-- Catch specific errors (`InvalidRequestError`, `AuthenticationError`, `RateLimitError`, or the base `CharmError`) and back off on rate limits.
-- Use the context manager (`with CharmClient(...) as client:`) so local deployments shut down cleanly.
-- Set credentials via env (`CHARM_API_KEY`, `CHARM_BASE_URL`) rather than hardcoding.
----
-### Decision guide
-#### When to use CHARM
-- Multivariate time series (multiple channels measured over time)
-- Each window has at least a few patches (patch size is 16, so ~48+ timesteps is a good floor)
-- You want a strong starting point without feature engineering
-#### When to use classical methods instead
-- Tabular data without a time dimension — use LightGBM, XGBoost
-- Very short series (< 10 timesteps)
-- Single scalar features — still works but may not outperform ARIMA/ETS
-#### Zero-shot vs fine-tuned
-| Approach | When | Effort |
-|---|---|---|
-| `prediction.create(target_len=H)` | Quick forecast baseline, no labeled data | None — one API call |
-| Embeddings + sklearn | Moderate data, combine with other features | Minutes |
-| Embeddings + kNN (retrieval/AD) | Unlabeled anomaly detection or search | Minutes |
-| Toolkit model (Reconstruction/Forecasting/Classification) | Have labeled data, want best performance | Train a small head (~minutes on CPU) |
----
 ## GIFT-Eval results
-Evaluated zero-shot on the full GIFT-Eval benchmark (97 dataset/frequency/term
-configurations) using the standard 11-metric protocol. Aggregate scores
-(geometric mean of per-config metrics normalized to the Seasonal Naive baseline;
-lower is better):
-| Metric | Score (rel. Seasonal Naive) |
-|---|---|
-| MASE | 0.7582 |
-| CRPS (mean weighted sum quantile loss) | 0.4776 |
 Per-term (geometric mean, normalized to Seasonal Naive):
-| Term | MASE | CRPS |
-|---|---|---|
-| short | 0.7463 | 0.5036 |
 | medium | 0.7577 | 0.4452 |
-| long | 0.7911 | 0.4460 |
-Scores are the geometric mean of per-config metric / Seasonal Naive across all
-97 GIFT-Eval configurations (lower is better; < 1.0 beats Seasonal Naive).
-Full per-config results are in `all_results.csv`.
 ## Evaluation protocol
 - Benchmark: GIFT-Eval, 97 configs (short / medium / long terms).
-- Metrics: MSE[mean], MSE[0.5], MAE[0.5], MASE[0.5], MAPE[0.5], sMAPE[0.5],
-  MSIS, RMSE[mean], NRMSE[mean], ND[0.5], mean_weighted_sum_quantile_loss
-  (computed with gluonts `evaluate_forecasts`).
 - Context length: 8192; forecasts are full quantile distributions.
-- Zero-shot: no GIFT-Eval train/test data is seen during pretraining
-  (`testdata_leakage = No`).
 ## Limitations
-- Forecast quality varies by domain and horizon; very long horizons and highly
-  non-stationary series remain challenging.
 - Quantile calibration is learned and may drift on out-of-distribution scales.
 ## Citation
-```
-@misc{charm,
-  title  = {CHARM: A Zero-Shot Time-Series Foundation Model},
-  author = {C3 AI},
-  year   = {2026},
-  url    = {https://huggingface.co/c3aiia3c/CHARM}
 }
 ```

   - foundation-model
   - zero-shot
   - gift-eval
+  - arxiv:2605.31580
 pipeline_tag: time-series-forecasting
 library_name: pytorch
 ---
 # CHARM
+CHARM (**CH**annel-**A**ware **R**epresentation **M**odel) is C3 AI's foundation model for
+**multivariate time series**. It is served behind an API and consumed through the open-source
+`c3-charm` Python SDK:
+- **Embeddings**: turn `(T, C)` windows into dense vectors for search, clustering, anomaly
+  detection and features.
+- **Zero-shot forecasting**: quantile forecasts and backcasts with no training data.
+- **Toolkit** (`charm_toolkit`): anomaly-detection recipes, retrieval metrics, and small
+  trainable heads for forecasting, reconstruction and classification.
+The model is channel-aware (channel names are part of the input) and normalizes internally, so you
+send raw values. It runs server-side; the SDK is the client.
+> **Availability:** CHARM model weights and training/replication code are **not publicly
+> released**. The model is served behind an API and consumed through the `c3-charm` SDK.
+## Use it
 ```bash
+pip install c3-charm   # Python >= 3.10
 ```
+Full SDK documentation (install, data format, client, embeddings, forecasting, anomaly detection,
+trained heads, HTTP API) ships inside the package — find it with
+`python -c "import charm.docs as d; print(d.get_docs_path())"` and start at `index.md`.
+Package: [c3-charm on PyPI](https://pypi.org/project/c3-charm/).
+## Getting access
+CHARM is served behind an API. Set `CHARM_BASE_URL` and `CHARM_API_KEY` to point the SDK at an
+endpoint. To obtain access, contact **gerardo.pastrana@c3.ai** and **dhruv.mehta@c3.ai**.
+The model will also be available on **Azure AI Foundry** — deployment instructions will be added
+here.
+## Using an AI coding agent?
+The **CHARM agent skill** teaches Claude Code, Cursor, Codex and others when and how to apply
+CHARM. Install it:
 ```bash
+claude plugin marketplace add https://huggingface.co/c3aiia3c/CHARM
+claude plugin install charm@c3-charm
 ```
+Other agents, or manual install: see [`skills/charm/README.md`](skills/charm/README.md).
+## Example notebooks
+Runnable notebooks (with sample data) live in [`notebooks/`](notebooks). Run them locally after
+`pip install "c3-charm[toolkit]"` (set `CHARM_BASE_URL` / `CHARM_API_KEY` first).
+| Notebook | What it covers |
+| --- | --- |
+| [getting_started.ipynb](notebooks/getting_started.ipynb) | Client setup, first embeddings call, inspecting `model_info()` |
+| [charm_toolkit_demo.ipynb](notebooks/charm_toolkit_demo.ipynb) | Tour of the toolkit: datasets, precompute, trainer, each task head |
+| [demo_forecasting.ipynb](notebooks/demo_forecasting.ipynb) | Zero-shot forecasting and the embedding-based ForecastingModel head |
+| [demo_reconstruction.ipynb](notebooks/demo_reconstruction.ipynb) | Backcast reconstruction and the ReconstructionModel head |
+| [demo_classification.ipynb](notebooks/demo_classification.ipynb) | Time-series classification with the ClassificationModel head |
+| [demo_retrieval_anomaly_detection.ipynb](notebooks/demo_retrieval_anomaly_detection.ipynb) | Embedding retrieval + kNN / zero-shot anomaly-detection recipes |
+## Model summary
+| Parameters             | ~63.3M (encoder ~59M)                                       |
+| ---------------------- | ----------------------------------------------------------- |
+| Hidden size (d_model)  | 384                                                         |
+| Projection             | TCN-pool (patch size 16, causal conv stack + residual gate) |
+| Backbone               | Transformer encoder with RoPE attention                     |
+| Decoder                | Quantile decoder, 99 levels (0.01–0.99)                     |
+| Max context length     | 8192                                                        |
+| Output                 | Probabilistic (quantile) forecasts, multivariate-capable    |
+| Precision              | float32                                                     |
+## Intended use
+Zero-shot probabilistic forecasting of univariate and multivariate time series across domains
+(energy, transport, sales, healthcare, nature, web/cloud-ops, econ/finance). The model is applied
+without any per-dataset fine-tuning.
 ## GIFT-Eval results
+Evaluated zero-shot on the full GIFT-Eval benchmark (97 dataset/frequency/term configurations)
+using the standard 11-metric protocol. Aggregate scores (geometric mean of per-config metrics
+normalized to the Seasonal Naive baseline; lower is better):
+| Metric                                 | Score (rel. Seasonal Naive) |
+| -------------------------------------- | --------------------------- |
+| MASE                                   | 0.7582                      |
+| CRPS (mean weighted sum quantile loss) | 0.4776                      |
 Per-term (geometric mean, normalized to Seasonal Naive):
+| Term   | MASE   | CRPS   |
+| ------ | ------ | ------ |
+| short  | 0.7463 | 0.5036 |
 | medium | 0.7577 | 0.4452 |
+| long   | 0.7911 | 0.4460 |
+Scores are the geometric mean of per-config metric / Seasonal Naive across all 97 GIFT-Eval
+configurations (lower is better; < 1.0 beats Seasonal Naive).
 ## Evaluation protocol
 - Benchmark: GIFT-Eval, 97 configs (short / medium / long terms).
+- Metrics: MSE[mean], MSE[0.5], MAE[0.5], MASE[0.5], MAPE[0.5], sMAPE[0.5], MSIS, RMSE[mean],
+  NRMSE[mean], ND[0.5], mean_weighted_sum_quantile_loss (computed with gluonts
+  `evaluate_forecasts`).
 - Context length: 8192; forecasts are full quantile distributions.
+- Zero-shot: no GIFT-Eval train/test data is seen during pretraining (`testdata_leakage = No`).
 ## Limitations
+- Forecast quality varies by domain and horizon; very long horizons and highly non-stationary
+  series remain challenging.
 - Quantile calibration is learned and may drift on out-of-distribution scales.
+## Paper
+Utsav Dutta, Gerardo Pastrana, Sina Khoshfetrat Pakazad, Henrik Ohlsson.
+*Giving Sensors a Voice: Multimodal JEPA for Semantic Time-Series Embeddings.* ICML 2026.
+[arXiv:2605.31580](https://arxiv.org/abs/2605.31580) ·
+[Hugging Face Papers](https://huggingface.co/papers/2605.31580)
 ## Citation
+```bibtex
+@inproceedings{dutta2026charm,
+  title     = {Giving Sensors a Voice: Multimodal JEPA for Semantic Time-Series Embeddings},
+  author    = {Dutta, Utsav and Pastrana, Gerardo and Khoshfetrat Pakazad, Sina and Ohlsson, Henrik},
+  booktitle = {Proceedings of the 43rd International Conference on Machine Learning (ICML)},
+  series    = {Proceedings of Machine Learning Research},
+  volume    = {306},
+  year      = {2026},
+  url       = {https://arxiv.org/abs/2605.31580},
 }
 ```
+## License
+Apache License 2.0 for the SDK and skill. See [c3-charm on PyPI](https://pypi.org/project/c3-charm/).
+Model weights are not released.