Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
DS-STAR
Running

App Files Community
DS-STAR
File size: 9,185 Bytes 
b4a7715
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b54f369
 
 
b4a7715
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
---
title: DS-STAR
emoji: ✨
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
license: mit
short_description: Multi-Agent AI System for Automated Data Science Tasks
tags:
- mcp-in-action-track-consumer
- langgraph
- multi-agent
- data-science
- automation
thumbnail: >-
  /static-proxy?url=https%3A%2F%2Fcdn-uploads.huggingface.co%2Fproduction%2Fuploads%2F658be22d0ccb77b89a142f5a%2Ft4RLYTRMF0_VHuQm5ZF91.png%3C%2Fspan%3E
social_media_post: https://x.com/AnuragDeo6/status/1995172899016380619
---

<div align="center">

# ✨ DS-STAR

### **D**ata **S**cience - **S**tructured **T**ask **A**nalysis and **R**esolution

[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Anurag-Deo/DS-STAR)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![LangGraph](https://img.shields.io/badge/Built%20with-LangGraph-orange)](https://langchain-ai.github.io/langgraph/)

**A powerful multi-agent AI system that automates data science tasks through intelligent collaboration.**

[🚀 Try Demo](https://huggingface.co/spaces/Anurag-Deo/DS-STAR) • [📖 Documentation](#-usage) • [🐛 Report Bug](https://github.com/Anurag-Deo/DS-STAR/issues)

</div>

---
<!-- Image of DS-STAR Architecture -->
![DS-STAR Architecture](/static-proxy?url=https%3A%2F%2Fcdn-uploads.huggingface.co%2Fproduction%2Fuploads%2F658be22d0ccb77b89a142f5a%2Ft4RLYTRMF0_VHuQm5ZF91.png%3C%2Fspan%3E)%3C%2Fspan%3E
---

## 🎯 What is DS-STAR?

DS-STAR is a **multi-agent AI system** built with LangGraph that takes your natural language questions about data and automatically:

1. 📊 **Analyzes** your data files to understand their structure
2. 📝 **Plans** a step-by-step approach to answer your question  
3. 💻 **Generates** Python code to perform the analysis
4. ✅ **Verifies** the solution meets your requirements
5. 🔄 **Iterates** with smart backtracking if needed
6. 🎯 **Delivers** polished, accurate results

> **Built for the 🤗 Hugging Face MCP 1st Birthday Hackathon**

---

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| 🤖 **Multi-Agent Architecture** | Six specialized agents working in harmony |
| 🔄 **Iterative Refinement** | Automatically improves solutions through multiple cycles |
| 🔙 **Smart Backtracking** | Intelligently reverts failed approaches |
| 📊 **Auto Data Analysis** | Understands your data structure automatically |
| 💻 **Code Generation** | Produces clean, executable Python code |
| 🌐 **Multi-Provider Support** | Works with Google, OpenAI, Anthropic, or custom APIs |
| 🎨 **Modern UI** | Beautiful dark-themed Gradio interface |

---

## 🏗️ Architecture

DS-STAR uses a sophisticated multi-agent workflow powered by LangGraph:

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Analyzer  │────▶│   Planner   │────▶│    Coder    │
│  📊 Analyze │     │  📝 Plan    │     │  💻 Code    │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Finalyzer  │◀────│   Router    │◀────│  Verifier   │
│  🎯 Polish  │     │  🔀 Route   │     │  ✅ Verify  │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  Backtrack  │
                    │  ↩️ Retry   │
                    └─────────────┘
```

### Agent Roles

| Agent | Role | Description |
|-------|------|-------------|
| **Analyzer** | 📊 | Examines all data files and creates detailed descriptions |
| **Planner** | 📝 | Generates the next logical step in the solution |
| **Coder** | 💻 | Implements the plan as executable Python code |
| **Verifier** | ✅ | Validates if the solution answers the query |
| **Router** | 🔀 | Decides to continue, add steps, or backtrack |
| **Finalyzer** | 🎯 | Polishes and formats the final output |

---

## 🚀 Quick Start

### Online Demo

Try DS-STAR instantly on Hugging Face Spaces:

👉 **[Launch DS-STAR Demo](https://huggingface.co/spaces/Anurag-Deo/DS-STAR)**

### Local Installation

```bash
# Clone the repository
git clone https://github.com/Anurag-Deo/DS-STAR.git
cd DS-STAR

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

Then open http://localhost:7860 in your browser.

---

## 💡 Usage

### Web Interface

1. **Select Provider** — Choose Google, OpenAI, Anthropic, or Custom
2. **Enter API Key** — Or set via environment variable
3. **Upload Data** — Drop your CSV, JSON, Excel, or Parquet files
4. **Ask Questions** — Type your data science question
5. **Run Analysis** — Click "Run Analysis" and watch the magic!

### Example Queries

```
📊 "What percentage of transactions use credit cards?"
📈 "Show me the distribution of transaction amounts"
🏆 "Which category has the highest total sales?"
🔗 "Find correlations between numeric columns"
📋 "Create a summary statistics report"
```

### Python API

```python
from src.graph import run_ds_star
from src.config import get_llm

# Initialize LLM
llm = get_llm(provider="google", model="gemini-2.0-flash")

# Run DS-STAR
result = run_ds_star(
    query="What is the average transaction amount?",
    llm=llm,
    max_iterations=20
)
```

---

## 🔌 Supported Providers

| Provider | Models | Environment Variable |
|----------|--------|---------------------|
| **Google** | Gemini 2.0, 1.5 Pro, 1.5 Flash | `GOOGLE_API_KEY` |
| **OpenAI** | GPT-4o, GPT-4, GPT-3.5 | `OPENAI_API_KEY` |
| **Anthropic** | Claude 3.5, Claude 3 | `ANTHROPIC_API_KEY` |
| **Custom** | Any OpenAI-compatible API | Custom Base URL |

---

## 📁 Project Structure

```
DS-STAR/
├── 📱 app.py                 # Gradio web application
├── 📜 main.py                # CLI entry point
├── 📋 requirements.txt       # Dependencies
├── 📂 src/
│   ├── 🤖 agents/            # Agent implementations
│   │   ├── analyzer_agent.py
│   │   ├── planner_agent.py
│   │   ├── coder_agent.py
│   │   ├── verifier_agent.py
│   │   ├── router_agent.py
│   │   └── finalyzer_agent.py
│   ├── 🔧 utils/             # Shared utilities
│   │   ├── state.py          # State schema
│   │   ├── formatters.py     # Text formatting
│   │   └── code_execution.py # Safe code execution
│   ├── ⚙️ config/            # Configuration
│   │   └── llm_config.py     # LLM setup
│   └── 🔄 graph.py           # LangGraph workflow
├── 🧪 tests/                 # Test suite
└── 📊 data/                  # Sample data files
```

---

## 🧪 Testing

```bash
# Run complete workflow test
python tests/test_complete_workflow.py

# Test individual agents
python -c "from src.agents import test_analyzer; test_analyzer(llm)"
```

---

## 🛠️ Configuration

### Environment Variables

```bash
# Set your API keys
export GOOGLE_API_KEY="your-google-api-key"
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
```

### Advanced Settings

| Setting | Default | Description |
|---------|---------|-------------|
| Max Iterations | 20 | Maximum refinement cycles |
| Temperature | 0.0 | LLM temperature (0 = deterministic) |

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Thanks to [DS-STAR](https://arxiv.org/abs/2509.21825) authors for inspiration
- Built with [LangGraph](https://langchain-ai.github.io/langgraph/) by LangChain
- UI powered by [Gradio](https://gradio.app/)
- Created for the [🤗 Hugging Face MCP 1st Birthday Hackathon](https://huggingface.co/)

---

<div align="center">

**Made with ❤️ by [Anurag Deo](https://github.com/Anurag-Deo)**

⭐ Star this repo if you find it helpful!

</div>