Atta

English | 中文

Atta is a parametric CAD kernel built for language models to drive. You describe a
part as a rebuildable spec, Atta computes the geometry in deterministic Python,
measures it, and only then lets a render or an export exist. An agent never has
to guess a shape from a screenshot, and it can prove the result is a closed solid
before claiming it is done.

Release: atta-1.2.2beta (1.2.2b3 in Python, 1.2.2-beta.3 in plugin packages).
Twelve geometry tools, 23 recipes, 47 feature ops. Blender is optional.

This beta adds rational NURBS patches, exact CAD fillets/chamfers with same-source STEP,
bounded fields, oriented module assembly and bio-inspired morphology ops. Camera, texture and look work live in the
separate basid program (bridge notes: BASID.md). See the
1.2.2beta release notes for capabilities and limits.

Why it is different

Principle	What it means in practice
Facts before pixels	`describe` returns bbox, volume, topology, wall thickness, rays and ASCII sections in under 0.3 s. A render is judgement, never evidence.
The spec is the model	A `model_id` stores how to rebuild, not a mesh blob. The same spec reproduces the same geometry hash.
Three-state gate	`verify` returns `pass` / `degraded` / `fail` with a receipt. `deliver` refuses anything that is not `pass` (or `degraded` with an explicit override).
Errors are patches	Every failure carries a `code`, a `path` and a concrete `fix` — not an apology.
Blender is a backend	Geometry, facts, verify and perception are pure numpy. Only renders and GLB/BLEND export need Blender.

Install

git clone https://github.com/laszapens/Atta.git atta && cd atta
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

Optional extras:

pip install -e ".[brep]"   # analytic STEP export (build123d / OpenCASCADE)
pip install -e ".[dev]"    # pytest + jsonschema, for running the test suite

Requires Python ≥ 3.10. Core dependencies are numpy, scipy, trimesh,
manifold3d and pillow — all installed by pip install -e ..

Quickstart

python3 -m atta doctor --deep                 # 1. is the engine healthy?
python3 -m atta catalog --verbose             # 2. what can it build? (23 recipes)
python3 -m atta model --recipe product.mug    # 3. build a draft in well under a second
python3 -m atta describe --wall               # 4. read the measured facts
python3 -m atta perceive --res 24             # 5. see it as text/ASCII, no render
python3 -m atta verify --level standard       # 6. gate it: pass / degraded / fail

model prints its model_id; every later verb defaults to the most recent model,
so you do not have to copy it around. Add --json to any command for the full
{ok, data, error} envelope instead of the human view.

When the verdict is pass, produce files:

python3 -m atta preview --mode studio --views hero --res 1200   # needs Blender
python3 -m atta deliver --formats glb,obj,stl                   # needs Blender

perceive looks like this — a sub-second viewfinder you can iterate against
without waiting on a render:

product.mug: 116.7x83.1x95.0 mm; aspect 1.00:0.71:0.81; V=93.69 ml;
closed=yes; genus=1; comps=1; convex=0.19; sym=y; holes~1; dih95=3.7

[front] coverage=0.481  # solid, . empty
....##########..........
....###########.........
...############.........
...###################..
..####################..
..#################.##..
..###############..###..
..###############..###..

The twelve tools

Every verb is also an agent tool with the same name (atta_ prefix).

Tool	One line
`atta_doctor`	Environment and capability self-check; run it first.
`atta_catalog`	Recipes, feature ops, materials, view and format lists, with parameter schemas.
`atta_spec`	`validate` / `propose` / `compile` / `schema` for a Spec v3 document — no geometry.
`atta_model`	Build from a recipe, a spec or a feature graph; `patches=` refines an existing spec.
`atta_variant`	Sample the parameter space, or solve real targets against measured metrics.
`atta_describe`	Facts, spatial probes, ASCII perception, construction trace, silhouette diff.
`atta_verify`	The three-state gate with a receipt you can store.
`atta_preview`	Studio/diagnostic renders plus image analysis. Needs Blender.
`atta_deliver`	Verify, then export GLB/OBJ/STL/BLEND (+ analytic STEP for a graph subset) with a manifest.
`atta_run`	Run a multi-step pipeline in one call, threading `model_id` between steps.
`atta_conjure`	Invent a parameterized build from an archetype, with explicit provenance.
`atta_design`	Inspect design heuristics and process constraints separately from geometry verification.

Geometry beyond primitives

Exact CAD — geometric edge selection, shared OCCT tessellation, and STEP
from the same fillet/chamfer construction. See CAD_FEATURES.md.
NURBS and fields — sampled rational patches and bounded composable fields,
with explicit error and budget reporting. See NURBS.md and
FIELD_TREE.md.
Modules and assemblies — oriented ports, deterministic attach, mates/DOF,
collision gates, and mixed exact/mesh STEP. See MODULE_ASSEMBLY.md.
Bio morphology — capsid, diatom, neuron, valve, lattice-shell and ring-stack
graph ops. Geometry, not biological simulation.
Look pipeline — texture sets, cameras and textured export are provided by
the separate basid package through the optional atta.look
bridge; Atta stays geometry-only.

The CLI adds two conveniences that are not tools: perceive (a shortcut for
describe --perceive) and tool <name> --args-file, the bridge the host plugins
use.

Spec v3

A spec is JSON. There are three model kinds; recipe is the short path.

{
  "schema": "atta.spec/v3",
  "name": "mug-01",
  "model": {"kind": "recipe", "id": "product.mug", "preset": "nominal",
            "params": {"height": 95, "wall": 3.2, "handle_enabled": true}},
  "quality": "draft",
  "material": "ceramic",
  "finish": {"bevel_mm": 0.6, "smooth_deg": 35},
  "constraints": {"bbox": {"z": [80, 120]}, "min_wall_mm": 2.4}
}

python3 -m atta model --spec-file examples/mug/spec.json

A graph spec is a DAG of feature ops, all arguments in mm:

{
  "schema": "atta.spec/v3",
  "name": "bracket-01",
  "model": {
    "kind": "graph",
    "output": "cut",
    "features": [
      {"id": "plate",  "op": "box", "args": {"size": [80, 50, 6]}},
      {"id": "hole",   "op": "cylinder", "args": {"radius": 4, "height": 20, "center": [14, 25, 3]}},
      {"id": "cut",    "op": "difference", "inputs": ["plate", "hole"]}
    ]
  },
  "constraints": {"bbox": {"x": [75, 85], "y": [45, 55]}, "volume_mm3": [15000, 26000]}
}

python3 -m atta model --spec-file examples/bracket/spec.json
python3 -m atta deliver --formats step          # analytic B-rep, no Blender needed

There are 47 ops: primitives, revolve/loft/loft2/sweep/sweep2, Coons and
Gordon patches, nurbs_surface, extrude, thicken, booleans, patterns,
transform/mirror, fillet/chamfer, offset/repair/subdivide, implicit
gyroid/sdf/sdf_blend/field_tree, text, and the bio morphology set
(capsid, branch_tree, pyramidal_neuron, diatom_frustule, perforated_valve,
perforated_cylinder, lattice_shell, pore_field_shell, ring_stack).
Arguments may use {"$param": "w"} or {"$expr": "w/2 + 4"}. atta_catalog --verbose
documents every op's required and optional keys.

The third kind, assembly, adds parts[], ports and 13 mate types, solved in
SE(3) with DOF from the Jacobian rank — see docs/ARCHITECTURE.md §8.

Connect an agent

MCP (any host)

The server is stdio JSON-RPC; print the config for your host and paste it in.

python3 -m atta.agent.install claude     # Claude Desktop JSON
python3 -m atta.agent.install cursor     # Cursor JSON
python3 -m atta.agent.install zcode      # merges into ~/.zcode/cli/config.json
python3 -m atta.agent.mcp                # or run the server directly

Every emitted entry uses absolute paths: python -m atta.agent.mcp with cwd,
ATTA_ROOT and PYTHONPATH set to this checkout. Restart the host afterwards to
load the atta_* tools.

DSH

python3 -m atta.agent.install dsh            # dry run: which profiles would change
python3 -m atta.agent.install dsh --create   # write dependency + bundle + symlink

The plugin lives in plugin/ and its skill in
plugin/skills/atta/SKILL.md. It shells out to
python3 -m atta, so it never re-implements geometry. Set ATTA_PYTHON if the
host's default interpreter cannot import atta, and ATTA_ROOT if the checkout
moves.

To install from Git, give the plugin manager the repository root URL:

dsh plugin --profile web add https://github.com/laszapens/Atta.git
# in the Web UI: Plugins -> Add plugin -> Git repository, same URL

The root package.json is a thin install shim (the real package
is plugin/package.json): it names @atta/dsh-atta,
declares dsh.bundle, and points main / dsh.bundle.patch into plugin/.
DSH requires the installed package to declare a bundle, so without that shim
the checkout installs as an empty placeholder and the manager refuses it with
declares no dsh.bundle. If you must install a subdirectory instead, a pnpm
path: spec works on pnpm 9 and later — but nothing on the plugin side needs it:

dsh plugin --profile web add 'https://github.com/laszapens/Atta.git#path:/plugin'

ZCode

Two options. The standalone MCP entry above is enough for the tools; the native
plugin adds a routing skill and the local marketplace.

python3 -m atta.agent.install zcode-plugin
# writes plugins/atta/.mcp.json (per-machine, git-ignored) from .mcp.json.example

Then in ZCode: Plugin Marketplace → Add → Add Plugin Marketplace → paste this
repo's plugins/ directory → Personal → dev-atta-local → Atta → Install.
Plugin files: plugins/atta/ and plugins/marketplace.json.
Enable either the standalone mcp.servers.atta entry or the plugin, not both, or
you will see duplicate tool listings.

HTTP bridge

python3 -m atta.agent.http --port 8765

curl -s localhost:8765/health
curl -s localhost:8765/tools
curl -s "localhost:8765/manifest?format=openai"
curl -s -X POST localhost:8765/call -H 'content-type: application/json' \
     -d '{"tool":"atta_model","args":{"recipe":"product.mug"}}'

Loopback only, no authentication: it is a local agent bridge, not a network
service. Do not expose the port.

Requirements and what works without Blender

Capability	Without Blender	With Blender
`doctor`, `catalog`, `spec`	yes	yes
`model`, `variant`, `describe`, `perceive`, `verify`, `run`	yes	yes
`deliver --formats step` (graph specs + `build123d`)	yes	yes
`deliver --formats glb,obj,stl,blend`	no — each file is reported `blender_unavailable`, `status: "partial"`	yes
`preview` (any mode)	no — `blender_unavailable`	yes

Mesh export degrades rather than crashing: deliver still verifies and writes the
manifest, and the file list marks each unexported format with a blender_unavailable
error and a fix. preview has nothing to fall back to, so it returns the error
directly — use describe --perceive instead when Blender is missing.

Atta finds Blender on PATH; set ATTA_BLENDER=/path/to/blender to pin a
specific build (it is authoritative — if it does not resolve, Atta reports no
Blender rather than silently using another one). doctor shows what it found.

Troubleshooting

Symptom	Cause and fix
`blender_unavailable`	Blender is not installed or not on `PATH`. Geometry, facts, verify and `perceive` still work; install Blender or set `ATTA_BLENDER` only when you need renders or mesh export. `deliver --formats step` is an analytic path that does not need Blender.
`no_models`	The workspace has no model yet, or `ATTA_HOME` points somewhere else. Run `model` first, or pass the `model_id` from an earlier result.
`unknown_recipe`	The id is misspelled. The error's `fix` lists all 23 valid ids; `catalog` shows their parameters.
Build says `status: "repaired"`	A parameter was outside its bounds and was clamped. Read `applied_patches` / `issues` — the model you got is not the one you asked for.
`deliver` returns `status: "blocked"`	`verify` did not pass. Fix the first entry in `verify.issues` (`fix` is populated) and rebuild; `degraded` needs an explicit `allow_degraded=true`.
Host plugin cannot `import atta`	The host is using a different interpreter than your venv. Set `ATTA_PYTHON` to the venv's python, or `pip install -e .` with the interpreter the host uses.
DSH: `插件安装失败 / 这个包没有声明组合包` (`declares no dsh.bundle`)	The Git URL resolved to a commit whose repository root has no `package.json`, so the installed dependency is a placeholder, not a bundle. Update to a commit that contains the root shim, or install `...Atta.git#path:/plugin`.

More detail: docs/ARCHITECTURE.md for how the layers fit,
docs/LLM_NATIVE.md for the agent-facing design rules,
docs/INTERFACES.md for the internal API contract,
docs/QUALITY.md for what "good" is checked against, and
docs/SHAPE_COVERAGE.md for what each recipe covers and
where the gaps are.

Repository layout

atta/            the Python package (numpy kernel + Blender backend + agent layer)
  families/      one auto-discovered module per shape category
  agent/         tool contracts, MCP, HTTP, manifests, host installers
  blender/       the only place that imports bpy
tests/           unit, contract and end-to-end tests
examples/        mug and bracket specs plus a batch pipeline
docs/            architecture, interfaces, LLM design notes, roadmap, coverage, quality
  assets/        identity mark (icon only)
plugin/          DSH plugin (the package: lib, skills, bundle patch)
plugins/         ZCode plugin + local marketplace
package.json     repository-root install shim for the DSH plugin (see DSH above)
corpus/bench/    held-out generalization cases
scripts/         maintainer tools (benchmark runner, corpus validator)

Contributing

Bug reports with a reproducing spec are the most useful contribution. See
CONTRIBUTING.md for how to add a recipe, add a feature op, run
the tests, and the code style the repository actually uses.

Atta is MIT licensed — see LICENSE.