Timecho AI
Python SDK for the Timecho AI time-series forecasting API. Provides synchronous and asynchronous clients, plus built-in CLI, MCP server, and agent skill/plugin integration surfaces for Qwen Code, Claude Code, and Codex.
This document has two parts:
- Part 1 · Using the released SDK — install from PyPI and use it (most users).
- Part 2 · Building from source — clone, build, self-check, and publish (contributors).
Requires Python ≥ 3.10. 中文版:README_ZH.md。
Part 1 · Using the released SDK
For versions published to PyPI — pip install and go.
Installation
pip install timecho_ai
Optional extras enable the integration surfaces:
pip install 'timecho_ai[cli]' # the timecho-ai command-line tool
pip install 'timecho_ai[mcp]' # the MCP server (timecho-ai-mcp)
pip install 'timecho_ai[plot]' # forecast plotting (plotly + kaleido)
pip install 'timecho_ai[all]' # everything above
| extra | dependencies |
|---|---|
| (core) | pandas, requests, aiohttp |
cli |
click, tabulate |
mcp |
click, tabulate, mcp[cli] |
plot |
plotly, kaleido |
all |
all of the above |
Configuration
Configure via constructor parameters or environment variables (constructor wins):
| Parameter | Environment Variable | Default | Description |
|---|---|---|---|
api_key |
TIMER_CLIENT_API_KEY |
- | API key for authentication (required) |
base_url |
TIMER_CLIENT_BASE_URL |
https://ai.timecho.com |
API base URL |
timeout |
TIMER_CLIENT_TIMEOUT |
30.0 |
Request timeout in seconds |
export TIMER_CLIENT_API_KEY="your-api-key"
Python SDK quick start
Synchronous client
import pandas as pd
from timecho_ai import TimechoAIClient
# Load your time series data
df = pd.read_csv("your_data.csv")
# Create a client (api_key may be omitted to read it from the environment)
client = TimechoAIClient(api_key="your-api-key")
# Test connectivity
print(client.hello_timer(name="World"))
# Forecast one or more targets from the complete input table. The boundary is required.
results = client.forecast(
data=df,
target="OT",
output_start_time=df["time"].iloc[2880],
output_length=720,
)
print(results[0].head())
# Select multiple target columns when the model supports multivariate output.
results = client.forecast(
data=df,
target=["OT", "HULL"],
output_start_time=df["time"].iloc[2880],
output_length=720,
)
print(results[0].head())
# Select covariate columns from the same input table.
results = client.forecast(
data=df,
target="OT",
history_cov=["hufl", "hull", "mufl", "mull", "lufl", "lull"],
future_cov=["hufl", "hull", "mufl", "mull", "lufl", "lull"],
output_start_time=df["time"].iloc[2880],
output_length=720,
)
print(results[0].head())
Asynchronous client
import asyncio
import pandas as pd
from timecho_ai import TimechoAIAsyncClient
async def main():
df = pd.read_csv("your_data.csv")
async with TimechoAIAsyncClient(api_key="your-api-key") as client:
print(await client.hello_timer(name="World"))
results = await client.forecast(
data=df,
target="OT",
output_start_time=df["time"].iloc[2880],
output_length=720,
)
print(results[0].head())
asyncio.run(main())
Forecast API
The keyword-only forecast method accepts one input table and one or more target columns:
| Parameter | Type | Required | Description |
|---|---|---|---|
data |
DataFrame |
Yes | One table containing the time column, target, and any covariate columns |
target |
str | Sequence[str] |
Yes | One or more unique numeric target column names; each must exist in data. A string is the one-target shorthand; use a list or tuple for multiple targets |
history_cov |
Sequence[str] |
No | Historical covariate column names from data; pass a list or tuple, in the desired order |
future_cov |
Sequence[str] |
No | Future covariate column names from data; pass a list or tuple and make it a subset of history_cov |
model_id |
str |
No | Model identifier; auto (default) routes by input shape |
quantile_levels |
Sequence[float] |
No | Strictly increasing quantiles inside (0, 1), including 0.5; mutually exclusive with prediction_interval_coverage |
prediction_interval_coverage |
Sequence[float] |
No | Central interval coverages such as 0.8; mutually exclusive with quantile_levels |
output_length |
int |
No | Forecast horizon, range [1, 720]. When omitted, the model default is used; with future covariates, their available length can define the horizon |
output_start_time |
str | Timestamp | datetime |
Yes | Boundary between history and future rows. It need not equal an input timestamp |
time_col |
str |
No | Name of the time column (auto-detected if not specified) |
auto_adapt_fill |
Mapping[str, object] |
No | Fill strategy for rows added while covariate lengths are always adapted. Omit for constant(0); otherwise use {"strategy": "constant", "value": number | "NaN"} or {"strategy": "edge" | "mean" | "median"} |
model_params |
dict |
No | Per-model inference parameters passed through to the server |
Point forecasts return the existing list of DataFrame. Probability forecasts return a list of QuantileForecastResult, exposing p50, quantile(q), all requested quantile frames, model/source metadata, and prediction_interval(coverage) when interval coverage was requested.
Probability forecasting requires an explicit model_id of timer or Chronos-2; None and auto are rejected locally. timer accepts only its native [0.1, 0.2, ..., 0.9] quantiles (central coverages 0.2, 0.4, 0.6, 0.8). Chronos-2 accepts valid quantiles throughout (0, 1) and the server interpolates non-native levels. The SDK always sends only the REST quantile_levels field; prediction_interval_coverage is expanded client-side using equal tails.
quantile = client.forecast(
data=df,
target="OT",
model_id="timer",
quantile_levels=[0.1, 0.5, 0.9],
output_start_time=df["time"].iloc[2880],
output_length=96,
)[0]
print(quantile.quantile(0.9))
interval = client.forecast(
data=df,
target="OT",
model_id="Chronos-2",
prediction_interval_coverage=[0.95],
output_start_time=df["time"].iloc[2880],
output_length=96,
)[0].prediction_interval(0.95)
print(interval.lower, interval.upper)
Input rules are enforced before the HTTP request:
time < output_start_timeis history;time >= output_start_timeis the future covariate window. Target values after the boundary are discarded.- The input table is stably sorted by the time column. Duplicate timestamps and inconsistent adjacent intervals are rejected with a validation error.
- Common ISO 8601 date/datetime forms are supported, with or without a timezone. The input representation and timezone state are preserved; values are not normalized to UTC, and
output_start_timemust use the same timezone state. - All selected value columns must be numeric. Original
NaNand infinite values are serialized as JSONnullso the service preserves them as unobserved; fill strategies apply only to newly added covariate rows, not internal missing values. - Covariate lengths are always adapted: history keeps the latest rows and is left-padded to target length; future keeps the earliest rows and is right-padded to
output_length. Padding defaults to0and can useconstant,edge,mean, ormedianthroughauto_adapt_fill. future_covmust be a subset ofhistory_cov; the SDK does not silently change an invalid role selection.- In the Python SDK,
target,history_cov, andfuture_covaccept sequences of column names. A comma-separated string is not implicitly split; use['a', 'b']or('a', 'b')for multiple columns.
Available models — auto, Timer-3.5, Timer-3.0, Chronos-2, toto2.0, timesfm2.5 — and their per-model limits (input/output length, covariate counts) are documented in doc/forecast_en.md, or read timecho_ai.FORECAST_LIMITS offline.
Command line (CLI)
Install the [cli] extra (and [plot] for --plot), then set your API key:
export TIMER_CLIENT_API_KEY="your-api-key"
timecho-ai hello # connectivity/auth smoke test
timecho-ai forecast --input data.csv --target OT --output-start-time 2024-01-06T00:00:00 \
--output-length 96 --time-col time --out pred.csv --plot pred.png
timecho-ai forecast --input data.csv --target OT --model-id Chronos-2 \
--prediction-interval-coverage 0.8 --output-start-time 2024-01-06T00:00:00 \
--output-length 96 --format json
forecastwrites the prediction to--out(or stdout); with--plotit writes a static PNG by default (opens in any image viewer, no network needed; size is controllable via--plot-width/--plot-height/--plot-scale). Use a.htmlpath or--plot-format htmlfor an interactive chart (which loads Plotly from a CDN).--targetis required at least once and accepts repeated or comma-separated column names (for example,--target OT --target HULLor--target OT,HULL). Use repeatable--history-covand--future-covoptions to select columns from the same input table; future columns must be a subset of history columns.--output-start-timeis required. Rows before it form history and rows at/after it form the future covariate window; irregular adjacent time intervals are rejected.--quantile-levelsand--prediction-interval-coverageare mutually exclusive, accept repeated or comma-separated probability values, and require--model-id timer|Chronos-2.- Connection options
--api-key/--base-url/--timeoutmirror theTIMER_CLIENT_*env vars. - Exit codes: 0 ok / 2 validation / 3 auth / 4 not found / 5 rate limit / 6 API/server / 7 connection·timeout / 8 missing deps.
Use in Qwen Code / Claude Code / Codex
Using Timecho AI inside an agent host is two steps: install and register the MCP server to expose forecasting to the model, then install the skill that orchestrates the model-choice → forecast → plot workflow. Below is the minimal setup per host in Qwen Code → Claude Code → Codex order; the full design (extension/plugin marketplaces, update flow, principles) is in doc/agent_integration_zh.md.
Common prerequisites: pip install 'timecho_ai[all]' and export TIMER_CLIENT_API_KEY=your-api-key. The MCP surface exposes only the forecast tool, which returns JSON records and, when a chart is requested, writes a PNG to disk and returns its absolute plot_path — open that file to view the chart. The shipped .mcp.json / extension manifests read ${TIMER_CLIENT_API_KEY} from the environment — never inline the key.
Qwen Code (Alibaba)
timecho-ai skill --install --target qwen # ~/.qwen/skills
qwen mcp add timecho-ai --scope user -e TIMER_CLIENT_API_KEY="$TIMER_CLIENT_API_KEY" -- timecho-ai-mcp
Note Qwen's stdio entry has no type field, and to load AGENTS.md into context set context.fileName to ["QWEN.md", "AGENTS.md"]. Verify with /mcp and /skills. The repo ships a native Qwen extension (plugins/qwen/, MCP declared inline); once open-sourced it installs in one step via qwen extensions install https://github.com/TimechoLab/Timecho-AI.
Claude Code
The repo is its own Claude Code marketplace + plugin (once open-sourced: claude plugin marketplace add TimechoLab/Timecho-AI then claude plugin install timecho-ai@timecho-ai). Manual path:
timecho-ai skill --install --target claude # ~/.claude/skills
claude mcp add --transport stdio --scope project \
--env TIMER_CLIENT_API_KEY=your-api-key timecho-ai -- timecho-ai-mcp
Verify with /mcp inside Claude Code.
Codex
The repo is also a Codex marketplace + plugin (once open-sourced: codex plugin marketplace add TimechoLab/Timecho-AI then codex plugin add timecho-ai@timecho-ai). Manual path:
timecho-ai skill --install --target codex # ~/.agents/skills + ~/.codex/skills
codex mcp add timecho-ai --env TIMER_CLIENT_API_KEY=your-api-key -- timecho-ai-mcp
Skill & updates
The bundled timecho-forecast skill drives the model-choice → forecast → plot workflow over the CLI/MCP surfaces (orchestration only — it never reimplements the SDK). timecho-ai skill --install defaults to --target all, installing into all three hosts (~/.claude/skills, ~/.agents/skills + ~/.codex/skills, ~/.qwen/skills); --target both is Claude+Codex only. Restart the host to load it; together with the registered MCP server the skill works inside the host. The CLI and MCP tools surface a "new version available" hint when a newer release is on PyPI; run timecho-ai update to upgrade the package and the skill together.
Plugin/extension-marketplace install requires this repository to be publicly fetchable, so it will be enabled once the repo is open-sourced. The repo is currently private; use the per-host
timecho-ai skill --install+ manual MCP registration above — every component ships in thetimecho_aipackage, so no repo clone is needed.
Part 2 · Building from source
For contributors, or to self-check the full flow before a release. Below is the complete path from a fresh clone to integration with Claude Code or Codex.
Prerequisites
- Python ≥ 3.10 (required by the official MCP SDK). Check:
python3 --version - git
- Plotting (optional):
[plot]pullsplotly+kaleido; kaleido 1.x downloads a headless Chrome on its first PNG render, so it needs outbound network access. - To register the MCP server with Claude Code, install the Claude Code CLI (
claude).
1. Get the source
git clone https://github.com/TimechoLab/Timecho-AI.git
cd Timecho-AI
2. Create a virtualenv and install
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
pip install -e '.[all]' # recommended for self-check: all extras
# or for development: pip install -e '.[dev]' (test/build/format + all extras)
See the extras table in Part 1; dev adds pytest / build / twine / black / isort on top of all.
3. Self-check: test / format / build
# Tests (mock-only, no real API key or network)
./scripts/run_tests.sh # or: python -m pytest tests/ -v
# Formatting & static checks
./scripts/format.sh # black + isort (auto-format)
./scripts/lint.sh # check-only (same as CI)
# Build wheel/sdist and verify
./scripts/build.sh # produces dist/timecho_ai-<ver>-py3-none-any.whl
./scripts/check.sh # twine check
Expected: tests all green (the 2 PNG-render tests skip automatically without a browser); the wheel contains timecho_ai/cli.py, timecho_ai/mcp_server.py, timecho_ai/_io.py and registers both timecho-ai and timecho-ai-mcp:
unzip -l dist/timecho_ai-*.whl | grep -E '_io|cli|mcp_server'
unzip -p dist/timecho_ai-*.whl '*entry_points.txt'
4. Run and verify from source
After setting your API key (see Configuration), the CLI / MCP / skill behave exactly as in the released package (see the Part 1 sections). Quick run with the official sample data:
export TIMER_CLIENT_API_KEY="your-api-key"
timecho-ai --version && timecho-ai hello
curl -o sample.csv https://ai.timecho.com/data/sample.csv
timecho-ai forecast -i sample.csv --target target -l 12 \
--output-start-time 2026-01-25 --time-col time --out pred.csv --plot pred.png
Register the MCP server with Claude Code (same as the released package — the timecho-ai-mcp command was installed into the venv by -e):
claude mcp add --transport stdio --scope project \
--env TIMER_CLIENT_API_KEY="$TIMER_CLIENT_API_KEY" timecho-ai -- timecho-ai-mcp
# then run /mcp inside Claude Code to verify timecho-ai and its forecast tools
Run the server manually (Ctrl-C to exit; stdout carries only JSON-RPC):
timecho-ai mcp serveorpython -m timecho_ai.mcp_server
5. Troubleshooting
| Symptom | Cause / fix |
|---|---|
pip install rejects the Python version |
Python ≥ 3.10 is required |
timecho-ai: command not found |
venv not activated, or the [cli]/[mcp] extra not installed |
| CLI prints "CLI requires the [cli] extra" | pip install -e '.[cli]' |
Plotting raises PlotDependencyError |
[plot] not installed, or kaleido cannot launch a headless Chrome (no network / no browser deps). Install [plot] and allow the Chrome download; fall back to CSV/JSON output if plotting is unavailable |
AuthenticationError (exit code 3) |
TIMER_CLIENT_API_KEY is not set |
/mcp doesn't list the server in Claude Code |
check timecho-ai-mcp is on PATH, .mcp.json is at the project root, and the launching shell injected the API key |
| MCP protocol / parse errors | stdout must stay clean — the server logs to stderr only; never print to stdout in a tool |
Self-check checklist (copy-paste)
git clone https://github.com/TimechoLab/Timecho-AI.git && cd Timecho-AI
python3 -m venv .venv && source .venv/bin/activate
pip install -U pip && pip install -e '.[dev]'
./scripts/lint.sh && python -m pytest tests/ -v
./scripts/build.sh && ./scripts/check.sh
export TIMER_CLIENT_API_KEY="your-api-key"
timecho-ai --version && timecho-ai hello
curl -o sample.csv https://ai.timecho.com/data/sample.csv
timecho-ai forecast -i sample.csv --target target -l 12 --output-start-time 2026-01-25 \
--time-col time --out pred.csv --plot pred.png
claude mcp add --transport stdio --scope project \
--env TIMER_CLIENT_API_KEY="$TIMER_CLIENT_API_KEY" timecho-ai -- timecho-ai-mcp
# then run /mcp inside Claude Code to verify
License
Metadata
Release files for timecho-ai 0.2.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| timecho_ai-0.2.6.tar.gz | 81.6 kB | Without provenance | Details for timecho_ai-0.2.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| timecho_ai-0.2.6-py3-none-any.whl | Python 3 | none | any | Details for timecho_ai-0.2.6-py3-none-any.whl |
Total release size: 165.8 kB
Release files / timecho_ai-0.2.6.tar.gz
| Download URL | timecho_ai-0.2.6.tar.gz |
|---|---|
| Size | 81.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e070d1a6c49c9b37a2dcb627008240959567431614d51dfc6d56f105c3587ebe
|
|
BLAKE2b-256 checksum How to use checksums |
e4aa59809f2fb1570fdf4a8b3e5f9b651940292a90e0a1012545351bccba21f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.12
|
Release files / timecho_ai-0.2.6-py3-none-any.whl
| Download URL | timecho_ai-0.2.6-py3-none-any.whl |
|---|---|
| Size | 84.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a2a9d4113e57fa10d218fb77db093ca45a245e17b94adb514b74068f42ef4e1d
|
|
BLAKE2b-256 checksum How to use checksums |
e92ead2b11c652fc4d0c4b423d96721c108bb4583962ab75444a216f5bfcb5fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.12
|
Security for timecho-ai 0.2.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.