timecho-ai 0.2.2

Python CLI SDK for Timecho AI API

Timecho AI

Python SDK for Timecho AI time series forecasting API. Provides both synchronous and asynchronous clients.

Installation

pip install timecho_ai

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

Configuration

The client can be configured via constructor parameters or environment variables:

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"

from timecho_ai import TimechoAIClient

# API key is read from environment variable automatically
client = TimechoAIClient()

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. Call client.list_models() to retrieve them at runtime, or read timecho_ai.FORECAST_LIMITS offline.

License

Apache License 2.0