timecho-ai 0.2.5

Python CLI SDK for Timecho AI API

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"))

# Univariate forecast
results = client.forecast(
    targets=df[["time", "OT"]][:2880],
    output_length=720,
)
print(results[0].head())

# Forecast with covariates
results = client.forecast(
    targets=df[["time", "OT"]][:2880],
    history_covs=df[["time", "hufl", "hull", "mufl", "mull", "lufl", "lull"]][:2880],
    future_covs=df[["time", "hufl", "hull", "mufl", "mull", "lufl", "lull"]][2880:3600],
    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(
            targets=df[["time", "OT"]][:2880],
            output_length=720,
        )
        print(results[0].head())

asyncio.run(main())

Forecast API

The forecast method accepts the following parameters:

Parameter	Type	Required	Description
targets	DataFrame	Yes	Target time series with a time column and one or more value columns
history_covs	DataFrame	No	Historical covariates (same length as targets)
future_covs	DataFrame	No	Future covariates (same length as output_length)
model_id	str	No	Model identifier; auto (default) routes by input shape
output_length	int	No	Forecast horizon, range [1, 720]. When omitted, the server applies the model's default (Timer-3.5: 272, others: 96)
output_start_time	Timestamp	No	Start time of the forecast output
output_interval	str	No	Time interval of the forecast output
time_col	str	No	Name of the time column (auto-detected if not specified)
auto_adapt	bool	No	Auto-adapt covariate lengths (default: True)
model_params	dict	No	Per-model inference parameters passed through to the server

Returns a list of DataFrame, one per forecast task.

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-length 96 \
    --time-col time --out pred.csv --plot pred.png

• 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).
• When --target is omitted, all non-time columns are forecast (with a warning).
• 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 \
    --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 --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