DeepFabric: synthetic training data with a topic graph, a Spin tool sandbox and a built-in evaluation pass
Generate High-Quality Synthetics, Train, Measure, and Evaluate in a Single Pipeline
At a glance
- What is it?
- DeepFabric is a Python pipeline that generates topic-anchored synthetic datasets, runs agent tool calls inside a WebAssembly sandbox, and evaluates the resulting models. It is aimed at teams already committed to fine-tuning who need coverage and schema conformance rather than raw volume.
- Who is it for?
- Adopt DeepFabric if you already fine-tune with TRL, Unsloth or Axolotl and your bottleneck is dataset coverage rather than compute. Do not adopt it if you want a hosted data service, or if you cannot run the Spin container, since the tool-calling path depends on it.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The coverage problem DeepFabric is built around
Most synthetic data generators sample from a prompt. You write a description of your domain, the model produces variations, and you get a few hundred rows that look different on the surface and repeat the same three ideas underneath. The README names this directly: the project claims its topic graph generation is what separates it from other dataset generation tools, because it covers subtopics while avoiding redundancy that leads to model overfit.
That is the specific problem. Not data volume, but whether the generated set spans the space you care about. DeepFabric is for people who have already decided to fine-tune a model and have discovered that their dataset, not their hyperparameters, is the limiting factor. It assumes you are comfortable with a CLI or a YAML file, that you have an API key for a hosted model provider, and that you will eventually push the result into a training framework rather than use it in place.
Topic graph generation and the arithmetic of depth and degree
The pipeline has two stages that can be run separately or through one config. The first builds a topic structure from a prompt. The second turns each topic node into a training sample. In the CLI example the README gives, --mode graph with --depth 3 and --degree 3 produces 27 unique nodes, and --num-samples 9 with --batch-size 3 yields 27 samples. The README describes that as 100% topic coverage, meaning one sample per node rather than a fixed count drawn at random.
The YAML equivalent splits this into a topics block and a generation block, with an optional shared llm block whose provider, model and temperature are inherited by both. The topics block takes prompt, mode (tree or graph), depth, degree and save_as, and can override the shared model, which the README's example does by dropping to gpt-4o-mini for topic generation while leaving the stronger model for sample writing. That override is the most practical detail in the config: topic enumeration is cheap and structural, sample generation is where you want the expensive model.
Tree mode and graph mode are not explained in the supplied material beyond the mode key accepting both values. Whether graph mode adds cross-links between branches or merges duplicate subtrees is not stated, so treat the difference as something to check in the docs before you pick.
Agent mode, the Spin sandbox and where tool calls actually run
Setting a tools block turns on agent mode implicitly, per the README. The conversation block then selects type: cot with reasoning_style: agent, and the tools block carries spin_endpoint, a components map, max_per_query and max_agent_steps. In the example, builtin routes read_file, write_file and list_files to /vfs/execute, with a cap of 3 tools per query and 5 ReAct reasoning iterations.
The execution environment is a Spin service the project ships as a Docker image. The README's note is explicit that the YAML example uses mocked tool execution and therefore requires a running Spin service, started with docker run -d -p 3000:3000 ghcr.io/nolabs-ai/deepfabric/tools-sdk:latest. The README describes these as isolated WebAssembly environments and says real tool executions happen there, which is the mechanism behind the claim that generated samples have execution correctness rather than just plausible-looking syntax.
There is also a scenario_seed block under tools that seeds files into the sandbox before generation. The example writes a Dockerfile into the virtual filesystem, so the model has something concrete to read and list. Tool definitions can be imported from MCP server schemas and mocked automatically, or taken from real interfaces, or drawn from a standard set of common tools. That import path is the part most likely to need reading the docs rather than the README, since the quickstart only shows the builtin component.
Getting it running: install, keys and the two entry points
Installation is a single pip command: pip install deepfabric. The CLI path needs a provider key exported in the environment, shown as export OPENAI_API_KEY="your-api-key". The generate command then takes --topic-prompt, --generation-system-prompt, --mode, --depth, --degree, --num-samples, --batch-size, --provider, --model and --output-save-as, writing JSONL to the path you give.
If you use tools, start the sandbox first: docker run -d -p 3000:3000 ghcr.io/nolabs-ai/deepfabric/tools-sdk:latest, then point spin_endpoint at http://localhost:3000. The image reference in the README has a stray backtick at the end, so copy the tag carefully.
The YAML route is a single config.yaml with the llm, topics and generation sections described above. The README does not show the command that consumes that file, which is a gap: you will need the docs site at docs.deepfabric.dev to find the invocation. Output goes to Hugging Face and can be imported into TRL, Unsloth or Axolotl according to the README, but no import snippet is given, so budget time for that wiring.
The Spin dependency is the real constraint
Every capability that distinguishes DeepFabric from a plain prompt-and-sample loop sits behind the Spin service. Constrained decoding and response validation are described as pipeline features, and real tool execution happens in the sandbox, so if you cannot run a container alongside your generation job, you are left with the topic graph and plain sample generation. That is still useful, but it is a much smaller product than the README's framing suggests.
The container also introduces a localhost assumption. The example endpoint is http://localhost:3000, which works for a developer laptop and becomes a networking question the moment generation runs on a build agent or a remote worker. Nothing in the supplied material covers authentication on that endpoint, port configuration, or what happens when the sandbox is unreachable mid-run. Treat the sandbox as a service you operate, not a library you import.
A second boundary: the project is Apache-2.0, which permits commercial use and modification, but the datasets you generate are shaped by whichever hosted model provider you point it at. Your provider's terms govern the output, not the Apache licence. Nothing here is legal advice, and the licence text says nothing about model output ownership.
How it differs from Distilabel and similar pipelines
Distilabel is the closest well-known comparison: a Python framework for synthetic data and AI feedback, built around composable pipeline steps and a strong emphasis on preference data and judge models. The difference in approach is where the structure comes from. Distilabel pipelines are assembled by the user from step classes, and diversity is generally a property of your prompt design and sampling. DeepFabric generates a topic structure first and then walks it, so coverage is a property of the graph parameters (depth, degree, mode) rather than of how many times you call the model.
The second difference is execution. Distilabel's tool-use and agent-oriented work generally assumes you supply the execution environment. DeepFabric ships one as a container and routes builtin tools to it, with max_agent_steps bounding the ReAct loop. If your evaluation depends on whether a tool call actually succeeded, that is the argument for DeepFabric. If you need fine control over pipeline composition and judge-model scoring, Distilabel's step model is the more direct fit. Both are Apache-2.0 Python projects, so the choice is about mechanism, not licensing.
Upgrade cadence and what it costs you
The release history shows a fast cadence: v4.10.1 in late January 2026, v4.11.0 the next day, v4.12.0 two days after that, with the last push to main in September 2026. Three point releases inside a week at the v4 line means the API surface is still moving. Pinning a version in your requirements file is the sensible default, and reading the release notes before each bump is worth the few minutes.
There is no stated long-term support branch, no deprecation policy and no compatibility matrix in the supplied material. The practical cost is not the install; it is the re-verification after each upgrade, because a change to the topic graph or the tools schema can shift your dataset distribution without failing loudly. If your fine-tuning runs are expensive, pin the version and regenerate a fixed evaluation set on every bump so you can see the drift.
The Apache-2.0 licence means you can vendor the code if upstream stalls, which is a reasonable hedge given the release tempo, but you inherit the maintenance of a fast-moving Python package if you do.
Editorial conclusion
Adopt DeepFabric if you already fine-tune with TRL, Unsloth or Axolotl and your bottleneck is dataset coverage rather than compute. Do not adopt it if you want a hosted data service, or if you cannot run the Spin container, since the tool-calling path depends on it. Before committing, verify the topic graph output on your own domain prompt, confirm the Spin image tag you pin actually serves /vfs/execute, and check which provider and model names your release supports.
Community notes