Skip to main content

Project Philosophy

Scope

ts-agents aims to be a CLI toolkit that lets autonomous agents do real, reproducible time-series work over long, multi-turn sessions. The same surface doubles as a practical “personal assistant data scientist” workbench for humans: fast, repeatable analysis with inspectable outputs.

It is not intended to be a monolithic end-user GUI product, and it is not “just an agent framework.” The durable value is in machine-readable tool contracts, domain priors, and reproducible execution that outlives any specific agent runtime.

Core Principles

1. CLI Is The Stable Contract

The ts-agents CLI is the primary automation surface. External agent frameworks consume that contract. Built-in agents and UI were removed in 0.4.0.

Why:

  • easy scripting and CI integration
  • easy debugging from command/log/artifact traces
  • easier harness swaps (Codex, Claude Code, custom agents) — the CLI outlives the agent runtime

1b. Machine-Readable Envelope For Autonomous Agents

--json output is versioned (schema_version), strict (no raw NaN), and typed. CLI envelopes carry top-level quality_status, degraded, and requires_review; workflow payloads carry result.status and result.data.quality_flags. Exit codes are typed for validation, dependency, permission, and timeout failures.

ts-agents capabilities --json, workflow show --json, and tool show --json are the agent bootstrap and discovery surface: they expose cli_templates, source_options, global_options, status_contract, and default_output_behavior so an agent can plan commands from metadata rather than hardcoded knowledge.

Why:

  • agents can branch on failure mode instead of parsing prose
  • bootstrap and discovery are a single round-trip
  • new agent runtimes can integrate without code changes in ts-agents

1c. Run Lifecycle As First-Class Metadata

Every workflow run gets a generated run ID, a run-scoped directory under outputs/<workflow>/<run-id>/, a run_manifest.json capturing inputs/params/ execution backend metadata/artifacts, and non-clobbering defaults with explicit --overwrite / --resume semantics. Resume reruns the same input and options; it does not recover a computational checkpoint.

Why:

  • long autonomous sessions remain traceable and safe to rerun
  • retry loops don’t corrupt previous outputs
  • downstream steps can materialize artifacts from any working directory

2. Framework Adapters, Not Framework Lock-In

LangChain/deep-agent integrations are convenience wrappers over the same tool registry and execution layer.

Why:

  • avoids rewriting time-series logic for each framework
  • keeps tool behavior consistent across interfaces
  • reduces migration risk as framework APIs change

3. Artifacts Over Chat

Chat is the control plane. Files are the product.

Tools should emit paths and structured outputs (plots, JSON, reports, logs) that can be reviewed, diffed, cached, and reused.

4. Skills Encode Domain Priors

SKILL.md runbooks are lightweight domain policies: ordering, defaults, and done criteria for real workflows.

Why:

  • lowers tool-selection errors
  • improves repeatability across agent runtimes
  • keeps knowledge in plain text, close to code

5. Sandboxes Handle Dependency Reality

Time-series stacks are dependency-heavy and often inconsistent across machines. Sandboxed backends isolate environments and provide resource controls.

Tradeoff:

  • better reliability and safety
  • more moving parts and potential latency/cost overhead

Practical Rule

Keep the CLI contract stable; iterate on analysis workflows and execution strategy around that stable core.