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_time is history; time >= output_start_time is 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_time must use the same timezone state.
• All selected value columns must be numeric. Original NaN and infinite values are serialized as JSON null so 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 to 0 and can use constant, edge, mean, or median through auto_adapt_fill.
• future_cov must be a subset of history_cov; the SDK does not silently change an invalid role selection.
• In the Python SDK, target, history_cov, and future_cov accept 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

• forecast writes the prediction to --out (or stdout); with --plot it 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 .html path or --plot-format html for an interactive chart (which loads Plotly from a CDN).
• --target is required at least once and accepts repeated or comma-separated column names (for example, --target OT --target HULL or --target OT,HULL). Use repeatable --history-cov and --future-cov options to select columns from the same input table; future columns must be a subset of history columns.
• --output-start-time is required. Rows before it form history and rows at/after it form the future covariate window; irregular adjacent time intervals are rejected.
• --quantile-levels and --prediction-interval-coverage are mutually exclusive, accept repeated or comma-separated probability values, and require --model-id timer|Chronos-2.
• Connection options --api-key/--base-url/--timeout mirror the TIMER_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 the timecho_ai package, 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] pulls plotly + 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 serve or python -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

Apache License 2.0