ds-cast

DS-CAST turns a folder of heterogeneous data and a natural-language question into a verified, reproducible answer — by driving a Claude Code agent through the plan → code → execute → verify → route loop from the DS-STAR paper (Google Cloud / KAIST), re-implemented on Claude Code's native primitives: subagents, skills, and hooks.

It is not a wrapper around an LLM. It is a symbiotic operating harness: the LLM makes only semantic judgements, while every action that mutates state — how a verdict becomes structured state, how results are captured, how the plan is truncated, how iter/status advance — is owned by deterministic Python scripts. That split is what makes the loop terminate, not silently ship unverified results, and survive a forgetful model.

How it works

/ds-star "<your question>"
   │  (main session = Controller + Coder, Opus)
   ├─ Phase 0  Init      create run + state.json, scan data/
   ├─ Phase 1  Analyze   parallel ds-analyzer subagents → one description per file
   ├─ Phase 2  Init plan  ds-planner → plan.md ; Coder writes solution.py ; dsstar-run
   └─ Phase 3  Loop
        ├─ ds-verifier  → verdict.json  (sufficient? — LLM-as-judge, gated)
        ├─ sufficient → Phase 4
        └─ else ds-router → router.json (add a step | backtrack to step l)
                 dsstar-plan truncate → ds-planner replans → Coder recodes → dsstar-run
                 (ds-debugger on exec failure, capped by max_debug_attempts)
        ▲ a Stop hook (loop_controller) enforces the loop deterministically
   Phase 4  /ds-finalize → atomically promote outputs/<run>/answer.md

For open-ended questions, /ds-research (DS-STAR+) decomposes the query into sub-questions, runs the core loop on each in isolated headless sub-runs, and writes a cited report.

The DS-STAR → Claude Code mapping

Why it's robust (design invariants)

• The gate never trusts an LLM-written flag. loop_controller derives whether to continue purely from deterministic artifacts; it never reads the advisory status.
• Termination is guaranteed by a stall backstop, not by iter≥M — counting consecutive blocks since iter last advanced, so a model that forgets to call advance still terminates.
• Results are captured deterministically. dsstar-run writes the full output to result.txt; the verifier reads the whole thing off disk while the session only sees a tail.
• Non-sufficient termination is never disguised as success. Finalize marks such answers unverified and promotes the best exec-ok, highest-score, non-superseded snapshot from history.
• One source of truth per fact: the plan lives only in plan.md; iter/status/ termination_reason are written only by dsstar-state.

Layout

CLAUDE.md            protocol overview + main-session rules (read this first)
pyproject.toml       uv deps + console_scripts (dsstar-run/plan/state)
src/dsstar/          deterministic helpers (pure stdlib)
.claude/
  settings.json      hook registration + permission allowlist
  skills/            ds-star, ds-plan, ds-finalize, ds-research
  agents/            ds-analyzer, ds-planner, ds-verifier, ds-router, ds-debugger, ds-generator
  hooks/             loop_controller.py (Stop), validate_subagent.py (SubagentStop)
.dsstar/runs/<id>/   internal state (transient, gitignored)
data/                read-only inputs
outputs/<id>/        durable deliverables (answer.md / report.md / solution.py / artifacts)

Quickstart

uv sync                         # set up the isolated environment
cp your_data.csv data/          # drop inputs into data/
# then, inside Claude Code:
/ds-star "What drives churn in this dataset, and quantify it."
/ds-research "Give me a full report on the sales trends and their causes."

Setup

Requires uv and Claude Code. After uv sync, the helper CLIs are available via uv run dsstar-run / uv run dsstar-plan / uv run dsstar-state. The .claude/ directory wires the subagents, skills, and hooks automatically when you open the project in Claude Code.

License

Licensed under the Apache License 2.0 © 2026 William Huang.

This is an independent, clean-room re-implementation inspired by the DS-STAR paper (arXiv:2509.21825, CC BY 4.0); it ships no code from the authors and is not affiliated with or endorsed by them.