# juleslscx/ds-star architecture

> Architecture diagram of the GitHub repository juleslscx/ds-star, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juleslscx/ds-star
- Repository: https://github.com/juleslscx/ds-star

## Overview

DS-STAR accepts data files and a query, analyzes the data, then iterates through planning, code generation and execution, debugging failures, and verifying/refining results before producing a formatted answer. Its CLI and pipeline controller also support resuming runs, interactive pauses, manual code edits, and artifact persistence. The README documents these capabilities and the provider options; the excerpts show the central pipeline, storage/controller responsibilities, and provider dispatch, but not all agent internals.

Main entry points: [`dsstar.py`](https://github.com/juleslscx/ds-star/blob/main/dsstar.py) (Pipeline Controller), [`provider.py`](https://github.com/juleslscx/ds-star/blob/main/provider.py) (Provider Dispatch), [`config.yaml`](https://github.com/juleslscx/ds-star/blob/main/config.yaml) (Run Configuration), [`prompt.yaml`](https://github.com/juleslscx/ds-star/blob/main/prompt.yaml) (Agent Prompts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Control"]
  node_cli["CLI<br/>[dsstar.py]"]
  node_config["Run Configuration<br/>[config.yaml]"]
  node_pipeline["Pipeline Controller<br/>[dsstar.py]"]
end

subgraph group_workflow["Analysis Workflow"]
  node_analyzer["Analyzer<br/>[dsstar.py]"]
  node_planner["Planner<br/>[dsstar.py]"]
  node_coder["Coder and Executor<br/>[dsstar.py]"]
  node_debugger["Debugger<br/>[dsstar.py]"]
  node_verifier["Verifier and Router<br/>[dsstar.py]"]
  node_finalizer["Finalizer<br/>[dsstar.py]"]
  node_prompts["Agent Prompts<br/>[prompt.yaml]"]
end

subgraph group_state["Run State"]
  node_artifacts[("Run Artifacts<br/>[dsstar.py]")]
  node_edit["Code Editing<br/>[dsstar.py]"]
end

subgraph group_models["Model Providers"]
  node_providers["Provider Dispatch<br/>[provider.py]"]
end

node_user(("User"))
node_data["Data Files"]
node_gemini["Gemini"]
node_openai["OpenAI"]
node_ollama["Ollama"]

node_user -->|"submits query"| node_cli
node_data -->|"provides inputs"| node_cli
node_config -->|"configures run"| node_cli
node_cli -->|"starts or resumes"| node_pipeline
node_pipeline -->|"runs analysis"| node_analyzer
node_pipeline -->|"requests plans"| node_planner
node_pipeline -->|"generates and executes"| node_coder
node_pipeline -->|"repairs failures"| node_debugger
node_pipeline -->|"checks results"| node_verifier
node_pipeline -->|"formats answer"| node_finalizer
node_pipeline -->|"saves and resumes"| node_artifacts
node_pipeline -->|"supports code edits"| node_edit
node_pipeline -.->|"uses prompts"| node_prompts
node_pipeline -->|"dispatches model calls"| node_providers
node_providers -->|"calls model"| node_gemini
node_providers -.->|"optionally calls"| node_openai
node_providers -.->|"optionally calls"| node_ollama
node_verifier -->|"refines plan"| node_planner

click node_cli "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_config "https://github.com/juleslscx/ds-star/blob/main/config.yaml"
click node_pipeline "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_analyzer "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_planner "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_coder "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_debugger "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_verifier "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_finalizer "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_prompts "https://github.com/juleslscx/ds-star/blob/main/prompt.yaml"
click node_artifacts "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_edit "https://github.com/juleslscx/ds-star/blob/main/dsstar.py"
click node_providers "https://github.com/juleslscx/ds-star/blob/main/provider.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_pipeline,node_user toneBlue
class node_analyzer,node_planner,node_coder,node_debugger,node_verifier,node_finalizer,node_prompts toneAmber
class node_artifacts,node_edit toneMint
class node_providers toneRose
class node_data,node_gemini,node_openai,node_ollama toneIndigo
```

## Components

### Entry and Control

- [CLI](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Run Configuration](https://github.com/juleslscx/ds-star/blob/main/config.yaml): `config.yaml`
- [Pipeline Controller](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`

### Analysis Workflow

- [Analyzer](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Planner](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Coder and Executor](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Debugger](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Verifier and Router](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Finalizer](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Agent Prompts](https://github.com/juleslscx/ds-star/blob/main/prompt.yaml): `prompt.yaml`

### Run State

- [Run Artifacts](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`
- [Code Editing](https://github.com/juleslscx/ds-star/blob/main/dsstar.py): `dsstar.py`

### Model Providers

- [Provider Dispatch](https://github.com/juleslscx/ds-star/blob/main/provider.py): `provider.py`

### Other components

- **User**
- **Data Files**
- **Gemini**
- **OpenAI**
- **Ollama**

## Connections

- User → CLI: submits query (evidence: `README.md`)
- Data Files → CLI: provides inputs (evidence: `README.md`)
- Run Configuration → CLI: configures run (evidence: `README.md`)
- CLI → Pipeline Controller: starts or resumes (evidence: `dsstar.py`)
- Pipeline Controller → Analyzer: runs analysis (evidence: `dsstar.py`)
- Pipeline Controller → Planner: requests plans (evidence: `dsstar.py`)
- Pipeline Controller → Coder and Executor: generates and executes (evidence: `README.md`)
- Pipeline Controller → Debugger: repairs failures (evidence: `README.md`)
- Pipeline Controller → Verifier and Router: checks results (evidence: `dsstar.py`)
- Pipeline Controller → Finalizer: formats answer (evidence: `dsstar.py`)
- Pipeline Controller → Run Artifacts: saves and resumes (evidence: `dsstar.py`)
- Pipeline Controller → Code Editing: supports code edits (evidence: `README.md`)
- Pipeline Controller → Agent Prompts: uses prompts
- Pipeline Controller → Provider Dispatch: dispatches model calls (evidence: `dsstar.py`)
- Provider Dispatch → Gemini: calls model (evidence: `README.md`)
- Provider Dispatch → OpenAI: optionally calls (evidence: `README.md`)
- Provider Dispatch → Ollama: optionally calls (evidence: `README.md`)
- Verifier and Router → Planner: refines plan (evidence: `README.md`)