Threadspool

Threadspool is an experimental self-learning embroidery engine for VP3 files, designed to be used through your AI agent / LLM harness of choice.

The interface is not a traditional app UI. It is the codebase itself.

New agent tasks should begin with AGENTS.md, which provides the project workflow, then use the design playbook and learnings as the design and VP3 knowledge base.

You describe what you want in natural language, the agent reads the available models, primitives, recipes, observations, and examples, then writes or updates the DesignSpec/scripts needed to produce embroidery artifacts on the fly.

For example:

Generate a croissant in a 100mm hoop. Each pastry piece should have a fill and a satin border.

Turn this uploaded image into an embroidery pattern using blue and green threads.

Write the text "EMBROIDERY" in 2mm thick strokes, where every letter is a different colour.

The agent turns a request into a concrete spec, compiles it through Threadspool, checks the output report, and updates the project knowledge when you provide import results or screenshots.

Examples

These designs were generated by Threadspool with GPT 5.5 and 5.6, and loaded into off the shelf embroidery software which displays a preview of the stitch patterns.

The Big Idea

I love to sew, and I love to embroider with my sewing machine (a Husqvarna Designer SE, which loads embroidery files sort of like how a 3D printer loads machine code). But I have two problems:

1. The software used to design embroidery files is really outrageously expensive. There are no open source alternatives, and the VP3 file type my machine needs does not have an open spec.
2. I'm a very terrible graphic designer when it comes down to making visuals, but I can describe what I want in great detail with words.

Threadspool is my answer to that: it is both a project that reverse-engineers and learns about the file format I need, and one that generates new designs and valid files that can be loaded onto the machine to turn into physical embroidery, without actually doing the traditional designing.

Threadspool is also an experiment in making that translation conversational. Instead of building a traditional design app with a fixed UI, the codebase becomes a set of embroidery-specific capabilities that an agent can use directly. The agent can inspect the existing primitives, learnings, recipes, and examples, then write the exact glue code or DesignSpec needed for the current request.

Most agent "skills" are markdown instructions. Threadspool is exploring a different pattern: skills as code plus accumulated project knowledge. The skills are not a rigid command list, and they are not hidden behind a GUI. They are Python models, helper functions, tests, sample observations, and generated examples that the agent can combine in new ways.

The repo contains deterministic embroidery capabilities:

• geometry models
• stitch primitives
• fill generators
• satin/run generators
• quality passes
• VP3 writing
• SVG preview rendering
• validation and tests

It also contains learning artifacts:

• docs/learnings.md for narrative lessons
• docs/observations/vp3 for structured observations
• reusable stitch recipes in threadspool/designs/recipes.py
• generated example specs in examples/vp3_debug

The agent uses all of that context as its working interface.

How Learning Works

The project was built from the ground up with GPT 5.5 and 5.6 in Codex, which started with absolutely zero knowledge about the proprietary file formats needed by embroidery machines, and built up its knowledge through our conversations alone.

The process was hugely collaborative between me and Codex, and started by me feeding it a few "real" VP3 files I had along with screenshots of what the designs looked like, so that it could try to interpret what portions of the file meant what, and how to represent different object types. Once it thought it understood what was the header portion vs the design portion, I would ask it to generate the simplest possible VP3, open it in actual embroidery software, look at what happened, then feed screenshots of the result back into the repo. At first, the majority of generated files were corrupt for unknown reasons, and it had to iterate with little feedback and learn on the fly. Once it had breakthroughs, it would log the learnings to the repo.

The first lessons came from minimal files and screenshots:

• a single horizontal line
• a circle outline
• two separated line segments
• the same geometry moved around in the hoop
• the same design resized
• two colors instead of one

Learning Examples

Each test isolated one behavior. If a circle appeared off-center, the next change focused on coordinate anchoring. If a line appeared in the wrong vertical position, the next change focused on Y direction. If only one color appeared, the next change focused on VP3 color-block separators. If the file imported as corrupt, the next change focused on headers, lengths, or stream structure.

Screenshots and photos were the feedback mechanism. I would open the generated VP3 in embroidery software, report the visible result, stitch count, color count, and dimensions, and then the agent would update the writer, compiler, examples, or notes. Over time, those small failures became working knowledge. Once proper VP3 files were being generated, if they showed up on the machine differently than they did in the preview software then I would send photos of that too.

Once the basics worked, the same process moved into harder embroidery skills:

• thread changes and color-block ordering
• centered placement and hoop extents
• running outlines
• satin stitches
• filled rectangles and ellipses
• cutout/crescent fills
• segmented fill rows
• angled fills
• real fill-density matching from a known-good sample
• multi-part dimensional designs with varied fill directions
• grouping same-thread pieces to avoid unnecessary thread swaps

The ongoing loop is:

1. Provide a VP3 sample, screenshot, size, color count, stitch count, or visual description.
2. The agent inspects or compares what it can, then records observations.
3. Useful lessons become docs, JSON observations, tests, recipes, or compiler behavior.
4. Future generated designs reuse those lessons.

Recent learned rules include:

• VP3 stores expanded stitch movements, not high-level fill objects.
• Dense fills that imported well use about 0.6mm row spacing and 1.0mm max stitch length.
• Satin detail lines look better with denser spacing around 0.35mm.
• Adjacent filled shapes should often use different fill angles for dimension.
• Satin outlines help separate fitted-together shapes.
• Output blocks should be grouped by thread color when layering does not require color alternation, so the machine does not ask for unnecessary thread swaps.

This is a living repo that will continue to evolve as more embroidery skills are learned. Embroidery path files can become incredibly complicated, with quite a bit more than just colours and shapes to take into account: just like with a 3D printer, there are physical limitations in the real world that affect whether a design will turn out, and implications such as thread weight, stacking patterns, and needle width to take into account.

Current Status

Threadspool can currently generate VP3 files. The output is useful and improving, but still experimental.

Working pieces:

• canonical model: Thread, ColorBlock, Design
• coordinate system: millimeters, origin at hoop center, +X right, +Y up
• schema and semantic validation for DesignSpec JSON
• deterministic primitives:
  • rect_fill, ellipse_fill, polygon_fill, crescent_fill
  • polyline_run, polyline_satin, circle_run, arc_run
  • text_bitmap, text_stroke
  • group, translate, scale, rotate, boolean_subtract, repeat
• quality pass with ties, min-stitch filtering, jump warnings, and trim insertion
• SVG previews with hoop boundary, center mark, per-color paths, and debug markers
• VP3 writer using the observed VSM container, metadata, extents, thread blocks, stitch streams, signed deltas, and jump commands
• learned recipe support via style_recipe

Known rough edges:

• travel paths and trim markers still need polish
• fill generation is scanline-based and still simpler than commercial digitizing
• VP3 compatibility is based on observed samples and import testing, given that it is not an open source file format

Using The Project

The intended interface is a coding agent inside your IDE.

Ask the agent to generate a design, improve a design, learn from a sample, or record an import result. The agent should read the repo, create or update specs, run the compiler, and write artifacts to out/.

For a fresh agent task, begin by asking it to read AGENTS.md. That guide is Threadspool's project memory: it explains the required design workflow, where the VP3 learnings live, how to create the SVG and DesignSpec, and how to compile and verify an import candidate. It then points the agent to the design playbook and nearby examples before it makes new geometry.

For example:

Read AGENTS.md and follow the Threadspool design workflow. Generate a [description] for a 100mm hoop, including a source SVG, DesignSpec, VP3, and stitch preview.

Good prompts:

• "Generate a cute strawberry with green leaves and black seeds."
• "Make a mushroom that uses different fill directions for each cap panel."
• "This imported correctly. Record the stitch count and what we learned."
• "Examine this valid VP3 file and learn how to replicate the fill stitch in the pink portion."

Command-Line Utility

generate_design.py still exists, but it is a utility, not the primary interface.

Use it when you already have a DesignSpec JSON and want to compile it directly:

python3 generate_design.py \
  --spec examples/vp3_debug/18_croissant_mirrored_panels.json \
  --out out/vp3_debug/18_croissant_mirrored_panels.vp3 \
  --preview out/vp3_debug/18_croissant_mirrored_panels.svg

It can also run the old heuristic prompt planner, but that path is mainly for smoke tests. The richer workflow is agent-driven because the agent can use the whole codebase, examples, and learning history instead of a fixed set of CLI commands.

Style Recipes

Specs can opt into learned stitch defaults with style_recipe. Object-level settings still override the recipe.

{
  "style_recipe": "learned_dense",
  "hoop_mm": { "width": 100, "height": 100 },
  "objects": [
    {
      "id": "shape",
      "type": "polygon_fill",
      "points": [[-10, 0], [0, 10], [10, 0]]
    }
  ],
  "blocks": [
    {
      "object_id": "shape",
      "thread": { "color_rgb": [111, 210, 70] }
    }
  ]
}

Current built-ins:

• basic: original conservative defaults
• learned_dense: fill spacing_mm=0.6, fill max_stitch_mm=1.0, fill fill_angle_deg=-10, satin spacing_mm=0.35, outline satin width_mm=1.1, and adjacent fill-angle step 25deg

For dimensional designs, use separate child objects for fitted-together pieces, assign varied fill angles, then group those children into thread-color blocks when possible.

Repository Map

• threadspool/core: internal model and transforms
• threadspool/stitches: stitch primitives and quality
• threadspool/designs: schema, compiler, recipes
• threadspool/export/vp3: VP3 writer
• threadspool/preview: SVG renderer
• threadspool/learning: profile experiments
• docs: accumulated learnings and observations
• examples: tracked DesignSpec examples
• out/: generated VP3/SVG artifacts, ignored by git

Tests

Run:

python3 -m unittest discover -s tests

The test suite covers schema validation, compiler behavior, transforms, recipe defaults, SVG rendering, and VP3 smoke checks.