timecho-ai 0.2.3

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 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 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.

MCP server

Expose forecasting to any MCP client (Claude Code, Codex, Claude Desktop, ...):

pip install 'timecho_ai[mcp]'
timecho-ai-mcp           # or: timecho-ai mcp serve  /  python -m timecho_ai.mcp_server

Register it with Claude Code (project scope writes a committed .mcp.json):

claude mcp add --transport stdio --scope project \
    --env TIMER_CLIENT_API_KEY=your-api-key timecho-ai -- timecho-ai-mcp

Register it with Codex:

codex mcp add timecho-ai --env TIMER_CLIENT_API_KEY=your-api-key -- timecho-ai-mcp

The repo ships a .mcp.json template that reads ${TIMER_CLIENT_API_KEY} from the environment — inject the key via env, never inline it. Verify with /mcp inside Claude Code. 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. (Pass return_image: true to additionally attach the PNG to the model's context; note many clients do not render tool-returned images inline, so the file is the reliable way to see it.)

Skill & plugins

A bundled timecho-forecast skill drives the model-choice → forecast → plot workflow over the CLI/MCP surfaces (orchestration only — it never reimplements the SDK). Install it into each host's skills directory:

timecho-ai skill --install                 # both Claude Code and Codex (default)
timecho-ai skill --install --target claude # Claude Code only (~/.claude/skills)
timecho-ai skill --install --target codex  # Codex only (~/.agents/skills + ~/.codex/skills)

The default --target both writes to ~/.claude/skills for Claude Code and, for Codex, to ~/.agents/skills plus the legacy $CODEX_HOME/skills (defaults to ~/.codex/skills); restart the host to load it. Together with the MCP server registered above, the skill works inside Claude Code / Codex.

The CLI and the MCP tools also 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. See doc/claude_code_integration_zh.md for the full integration & update design.

Plugin-marketplace install (claude plugin marketplace add / codex plugin marketplace add) requires this repository to be publicly fetchable, so it will be enabled once the repo is open-sourced — at that point TimechoLab/Timecho-AI can be used as the marketplace source to install the skill + MCP in one step. The repo is currently private; use the skill --install + manual MCP registration shown above.

---

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