Metadata-Version: 2.4
Name: c3-charm
Version: 0.1.17
Summary: Python SDK for the CHARM time-series foundation model — embeddings, forecasting, and a downstream-task toolkit.
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: time-series,embeddings,forecasting,foundation-model,anomaly-detection
Author: C3 AI
Author-email: opensource@c3.ai
Requires-Python: >=3.10
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Provides-Extra: toolkit
Requires-Dist: datasetsforecast (>=0.1.0) ; extra == "toolkit"
Requires-Dist: dill (>=0.3.7) ; extra == "toolkit"
Requires-Dist: gin-config (>=0.5.0) ; extra == "toolkit"
Requires-Dist: httpx[http2] (>=0.25.0)
Requires-Dist: lightgbm (>=4.0.0) ; extra == "toolkit"
Requires-Dist: matplotlib (>=3.7.0) ; extra == "toolkit"
Requires-Dist: minisom (>=2.3.1) ; extra == "toolkit"
Requires-Dist: numpy (>=1.24.0)
Requires-Dist: optuna (>=3.0.0) ; extra == "toolkit"
Requires-Dist: pandas (>=2.0.0) ; extra == "toolkit"
Requires-Dist: pyarrow (>=14.0.0) ; extra == "toolkit"
Requires-Dist: python-dotenv (>=1.0.0)
Requires-Dist: requests (>=2.31.0)
Requires-Dist: scienceplots (>=2.0.0) ; extra == "toolkit"
Requires-Dist: scikit-learn (>=1.3.0) ; extra == "toolkit"
Requires-Dist: seaborn (>=0.13.0) ; extra == "toolkit"
Requires-Dist: tensordict (>=0.1.0) ; extra == "toolkit"
Requires-Dist: tqdm (>=4.60.0)
Project-URL: Documentation, https://huggingface.co/c3aiia3c/CHARM
Project-URL: Homepage, https://c3.ai
Project-URL: Issues, https://huggingface.co/c3aiia3c/CHARM/discussions
Project-URL: Repository, https://huggingface.co/c3aiia3c/CHARM
Description-Content-Type: text/markdown

# c3-charm

[![PyPI version](https://img.shields.io/pypi/v/c3-charm.svg)](https://pypi.org/project/c3-charm/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/pypi/pyversions/c3-charm.svg)](https://pypi.org/project/c3-charm/)

Python SDK for **CHARM**, C3 AI's foundation model for multivariate time series.

- **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.
- **Imputation**: fill missing values, with quantiles.
- **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; this package is the client. To get an endpoint and key,
see [Getting access](https://huggingface.co/c3aiia3c/CHARM#getting-access) on the model card.

## Install

```bash
pip install c3-charm                            # core SDK (Python >= 3.10), no torch

# Toolkit (anomaly detection, retrieval, trainable heads) needs PyTorch.
# Install the CPU wheel first, then the toolkit:
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install "c3-charm[toolkit]" nest-asyncio
```

See [installation.md](installation.md) for details.

## Quick look

```python
from charm import CharmClient

client = CharmClient(base_url="https://your-charm-server:8080", api_key="...", timeout=300)

fc = client.prediction.create(
    descriptions=[["load_mw", "ambient_temp"]],  # (N, C) channel names
    ts_array=[history],                          # (N, T, C) raw values as nested lists
    target_len=24,                               # > 0 forecast, < 0 backcast
    return_tensors="np",
)
fc.median                     # (N, 24, C) point forecast
fc.denormalized_predictions   # (N, 24, C, Q) quantiles

emb = client.embeddings.create(descriptions=..., ts_array=..., return_tensors="np").embeds  # (N, D)
```

## Using an AI coding agent?

There's a **CHARM agent skill** that teaches Claude Code, Cursor, Codex and others when and how to
apply CHARM, routing them to these docs for the exact API. Install it from
<https://huggingface.co/c3aiia3c/CHARM>.

## Documentation

Full documentation ships with the package. Find it with
`python -c "import charm.docs as d; print(d.get_docs_path())"` and start at
[index.md](index.md). It covers concepts and a decision guide, data format, client configuration,
embeddings and retrieval, forecasting, anomaly detection, trained heads, and errors plus the raw
HTTP API.

## License

Apache License 2.0. See [LICENSE](https://www.apache.org/licenses/LICENSE-2.0).

