Dugalaxy

Ask a chatbot for test data and you get five samples that drift, repeat, and contradict each other. Ask again tomorrow and you get five different ones. And when something fails on sample #3,412, nobody can say what the correct answer was, because there never was one.

Dugalaxy generates data that knows its own answers.

You describe your data once, as a reusable template. From then on, a seeded engine invents the facts of every scenario first (the order id, the refund amount, the customer's actual problem), and the model is only allowed to write prose around facts it was handed. The ground truth exists before the text does. Every sample lands on disk with its facts attached, so whether you generate ten samples or ten thousand, you always know what the right answer was.

That one property is the whole point. It is what makes the output usable as evaluation input for an AI agent, seed data for an empty database, or a fine-tuning set, instead of plausible-looking noise.

Status: early, and actively built in the open. v1 focuses on Template mode. Expect rapid iteration. Issues and feedback are very welcome.

---

Get started in four steps

# 1. Install
pip install dugalaxy

# 2. Run it with no arguments and it guides you from there
dugalaxy

# 3. See it work instantly (zero setup: no model, no key, no config)
dugalaxy gen quickstart

# 4. Make your own from one sentence
dugalaxy new "short angry support emails about late refunds, each with an order id and a refund amount"

Step 2 walks you through everything interactively. If you'd rather drive yourself:

• dugalaxy is the guided first run. It gives you an instant win, then offers to build your own template. In a script or a pipe it just prints help and exits; it never hangs.
• dugalaxy gen quickstart generates fully deterministic synthetic profiles. The seeded engine writes every field, so it needs no model at all. Real output the second you install.
• dugalaxy new "<description>" drafts a template from your sentence, validates it against the real loader (retrying if it has to), and saves ./<slug>.yaml. No model available? It starts you from the closest bundled example instead, so you are never blocked. Treat the result as a starting point to skim, not a verified dataset.
• dugalaxy gen <your-template> generates from your template: one sample first, then --n N for more.
• dugalaxy doctor checks your setup in plain words and tells you the one thing to fix next.

Before each run, Dugalaxy prints exactly what it is about to do: sample count, seed, target model, output location, an estimated cost, and a duplicate-risk warning. Paid runs sit behind a confirmation. Afterwards it reports produced/dropped/retries plus a diversity metric, so variety is provable rather than promised. Output is written incrementally as JSONL (the lingua franca of LLM eval and fine-tune datasets) and as a YAML dataset envelope; pick with --format.

New here? Follow the getting-started walkthrough.

---

Why this is a tool, not an LLM wrapper

Three design decisions. Each is simple; they only pay off together.

1. The template is a durable asset. You author the intent once and regenerate forever with one command. No re-explaining yourself to a chatbot every time the data runs out.
2. The facts are decided before the prose. The model never invents structured facts. A seeded engine generates the ground truth of each scenario; those facts are serialized into structured payloads (valid by construction) and handed to the model as given truth. The model writes free-form prose and nothing else. This is where the answer key comes from.
3. Everything goes straight to disk. Each sample is written out as it is produced. The model's context never accumulates prior output, so generation scales indefinitely at flat cost, and sample 5,000 is as good as sample 5.

Want to write or tune a template by hand? The template spec is the full reference, though you never need to read it to get started.

---

Bring your own model

Dugalaxy talks to OpenAI-compatible APIs (OpenAI, DeepSeek, Groq, Together, and friends), Anthropic, and local models via Ollama. Local is the default: fully offline, zero API cost. Using a hosted model instead takes two small steps.

1. Put a dugalaxy.config.yaml in the directory you run from (it is read from your current working directory):

provider: openai_compatible
base_url: https://api.openai.com/v1
model: gpt-4o-mini
api_key_env: OPENAI_API_KEY     # the NAME of the env var, never the key itself
cost_cap_usd: 1.00

2. Set the environment variable that holds your key. It lives only in that terminal window; API keys are never read from a file on disk:

$env:OPENAI_API_KEY = "sk-your-key-here"     # Windows PowerShell

export OPENAI_API_KEY="sk-your-key-here"     # macOS / Linux

Then run dugalaxy doctor to confirm the config, provider, and key are all green. Prefer no file? Pass --provider/--model/--api-key-env as flags instead. Precedence is CLI flags > config file > template defaults.

Templates that contain no model-written prose run fully deterministically: no model, no API key required.

---

A note on the data

Everything Dugalaxy produces is synthetic test data. Names, emails, IDs, and timestamps come from a seeded engine, not from real people or systems. It is meant for evaluating, fine-tuning, and testing software. The structured facts are guaranteed valid by serialization; model-written prose is checked structurally only (length, fact-presence), never for semantic correctness.

---

Documentation

• Getting started
• Template spec
• Changelog
• Contributing
• Security policy

License

AGPL-3.0-only. Free for any internal use. If you offer Dugalaxy as a hosted or commercial service, the AGPL requires you to open-source your whole stack. For commercial licensing without that obligation, open an issue to start a conversation.