OpenDsStar

DS-STAR (Data Science - Structured Thought and Action) is an open-source, Python-based agentic framework designed to fully automate complex data science tasks. Based on Google Research's paper, [[DS-STAR]]: A State-of-the-Art Versatile Data Science Agent, this framework orchestrates a collaborative network of specialized AI agents to analyze data, generate code, and iteratively refine solutions to address user queries.

DS-Star GitHub Project Overview

• Agentic Workflow: Implements a pipeline of specialized AI agents (Analyzer, Planner, Coder, Verifier, Router, Debugger, and Finalyzer) that collaborate to solve complex data science tasks.
• Full Reproducibility: Every phase of the execution is saved locally—including prompts, generated Python code, execution results, and metadata—allowing for complete auditability.
• Interactive & Resume-able: Execution runs can be paused and resumed. An interactive mode enables step-by-step human evaluation before moving to the next phase.
• Code Editing & Debugging: Allows users to manually edit generated Python code during a run, and features an auto-debug agent to dynamically resolve code execution errors.
• Configuration-driven: Project configurations, model parameters, and global run configurations are easily managed through a centralized config.yaml file.

The DS-STAR pipeline executes in three main phases:

1. Analysis: The Analyzer agent inspects the initial dataset files (e.g., CSV, Excel) and generates descriptive summaries.
2. Iterative Planning & Execution:
   • The Planner creates an initial step-by-step plan to answer the user's prompt.
   • The Coder generates Python code to execute the active step of the plan.
   • The system runs the generated code and captures the output.
   • If the code fails, an automatic Debugger agent attempts to fix the logic and syntax.
   • The Verifier checks whether the resulting execution sufficiently answers the target query.
   • The Router determines the next step: either finalize the workflow or loop back to add refinement steps. This loop runs until the plan is complete or the maximum refinement rounds limit is met.
3. Finalization: The Finalyzer takes the final code execution results and packages them into a clean, specified output structure (such as JSON).

All artifacts generated during a run are structured and saved under the runs/ directory using a unique run_id.

/
├─── dsstar.py               # Main script containing the agent logic and CLI
├─── config.yaml             # Main configuration file
├─── prompt.yaml             # Prompts for the different AI agents
├─── pyproject.toml          # Project metadata and dependencies (uv format)
├─── uv.lock                 # Locked dependency versions for reproducibility
├─── .python-version         # Python version specification for uv
├─── data/                   # Directory for your data files
└─── runs/                   # Directory where all experiment runs and artifacts are stored

• Python 3.11+
• An API key for Google's Gemini models (or other supported providers)
• uv package manager (recommended for fast dependency resolution)

To set up the project locally using uv:

# Clone the repository
git clone https://github.com/JulesLscx/DS-Star.git
cd DS-Star

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with uv
uv sync

1. Set your API Key: Set your Gemini API key as an environment variable:

   export GEMINI_API_KEY='your-api-key'
   

   Alternatively, you can add it directly to your config.yaml file.

2. Customize config.yaml: Create a config.yaml file in the root of the project to customize model parameters:

   # config.yaml
   model_name: 'gemini-1.5-flash'
   max_refinement_rounds: 5
   interactive: false
   # api_key: 'your-api-key' # Alternatively, place it here
   
   # Optional: Configure specific models for different agents
   agent_models:
     PLANNER: 'gpt-4'
     CODER: 'gemini-1.5-pro'
     VERIFIER: 'gemini-1.5-flash'
   

Place your target data files (e.g., .xlsx, .csv) inside the /data directory.

• Start a New Run: Provide target files and a query via the CLI.

  uv run python dsstar.py --data-files file1.xlsx file2.xlsx --query "What is the total sales for each department?"
  

• Resume a Run: If an agent pipeline is interrupted, resume it using its unique run_id.

  uv run python dsstar.py --resume <run_id>
  

• Edit Code Mid-Run: You can manually modify the last generated chunk of code and re-run it. This is useful for custom tweaking or manual debugging.

  uv run python dsstar.py --edit-last --resume <run_id>
  

  Note: This command opens the code file in your system's default text editor (e.g., nano, vim). Saving and closing the editor triggers the script to run the updated code.
• Interactive Mode: To step through and manually approve each phase before executing:

  uv run python dsstar.py --interactive --data-files file1.csv --query "Analyze the year-over-year growth rate"
  

The following settings are configurable via config.yaml or can be overridden directly using CLI arguments:

DS-STAR supports multiple AI model backends. Each provider expects corresponding environment variables:

• Provider Identifier: Default provider (no prefix required)
• Environment Variable: export GEMINI_API_KEY='your-gemini-api-key'
• Model Examples: gemini-2.5-pro, gemini-2.0-flash, gemini-1.5-pro

• Provider Identifier: Models prefixed with gpt or o1
• Environment Variable: export OPENAI_API_KEY='your-openai-api-key'
• Model Examples: gpt-4, gpt-4-turbo, o1

• Provider Identifier: Models prefixed with ollama/
• Environment Variables:

  export OLLAMA_API_KEY='your-ollama-api-key'  # Optional
  export OLLAMA_HOST='http://localhost:11434'  # Optional, defaults to localhost
  

• Model Examples: ollama/llama3, ollama/qwen3-coder

This project uses the fast Python packaging tool uv for dependency resolution.

• Performance: uv resolved installations are 10–100x faster than standard pip.
• Deterministic Builds: Lockfiles protect environmental stability.
• Seamless Executions: No virtual environment activation is needed; commands execute natively using uv run.

• Install dependencies: uv sync
• Add a dependency: uv add <package-name>
• Remove a dependency: uv remove <package-name>
• Update packages: uv sync --upgrade
• Run a script: uv run python <script.py>
• Show active environment packages: uv pip list

Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs or feature requests directly on the JulesLscx/DS-Star GitHub Repository.

• Multi-Agent Orchestration: Implements specialized roles (planning, coding, debugging, and verification) working in tandem to deliver highly reliable data science execution.
• Developer-in-the-Loop: Offers flexible manual code intervention, interactive prompt validations, and structured error correction.
• Auditability & Logging: Tracks execution history and preserves physical pipeline artifacts inside the local runtime logs.
• Multi-Provider Flexibility: Integrates seamlessly with Google Gemini, OpenAI, and local Ollama models.