Metadata-Version: 2.4
Name: chip-cnc
Version: 0.1.3
Summary: Type what you want carved. Chip designs it, checks it, and carves it on a FoxAlien XE-Ultra 8080 CNC — no CAM software, no G-code, no jargon.
Project-URL: Homepage, https://github.com/brettbergin/chip
Project-URL: Source, https://github.com/brettbergin/chip
Project-URL: Issues, https://github.com/brettbergin/chip/issues
Project-URL: Changelog, https://github.com/brettbergin/chip/blob/main/CHANGELOG.md
Project-URL: Releases, https://github.com/brettbergin/chip/releases
Author-email: Brett Bergin <brettberginbc@yahoo.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,carving,cnc,foxalien,grbl,pydantic-ai,woodworking
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Manufacturing
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Requires-Python: >=3.12
Requires-Dist: fonttools>=4.50
Requires-Dist: keyring>=24.0
Requires-Dist: pillow>=10.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic-ai>=2.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.7
Requires-Dist: pyserial>=3.5
Requires-Dist: pyside6>=6.7
Requires-Dist: shapely>=2.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: svgelements>=1.9
Requires-Dist: svgwrite>=1.4
Provides-Extra: dev
Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
Requires-Dist: mdformat-frontmatter>=2.0; extra == 'dev'
Requires-Dist: mdformat-gfm>=0.3; extra == 'dev'
Requires-Dist: mdformat>=0.7; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-qt>=4.4; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: types-pyserial>=3.5; extra == 'dev'
Provides-Extra: trace
Requires-Dist: vtracer>=0.6; extra == 'trace'
Description-Content-Type: text/markdown

# Chip

**Type what you want carved. Chip does the rest.**

Chip is a desktop app that turns a plain-English sentence — *"a sign that
says The Hendersons with a pine tree on each side"* — into a finished carving
on a [FoxAlien XE-Ultra 8080](https://www.foxalien.com/) CNC machine. No CAM
software, no G-code, no file formats, no settings panels: describe the
design, check the preview, clamp the board, press start.

## What it does

- **Design from a sentence.** An AI designer lays out text, clip-art, and
  borders on your board, sized and centered sensibly. Refine it by dragging
  things around or just typing "make the name bigger". Every change —
  including the AI's — is undoable. No API key or internet? Built-in
  templates and full manual editing still work.
- **Plain-language everything.** Dimensions are fractional inches (3/4",
  1-1/2"). Carve styles are "lines", "scooped out", and "cut through".
  Machine errors are translated into what happened, whether your workpiece
  is okay, and what to do next — never a raw error code.
- **A guided carve, end to end.** The app generates the toolpaths, walks
  through clamping, bit installation (with a picture of the right bit),
  setting the start point, and Z-probing — then streams the job with live
  progress and a STOP button that is always on screen. Multi-bit jobs pause
  for a guided bit change with a mandatory re-probe.
- **Safety interlocks in software.** No motion without an explicit press;
  carves refuse to start unless the machine is homed, zeroed, and the job
  fits the work envelope; STOP needs no confirmation and always works.
- **An escape hatch.** Any design exports as a true-size SVG (text as
  paths, pocket fills, engrave strokes) that imports cleanly into Easel
  Pro or other CAM tools for jobs beyond Chip's scope.

> **Honesty section:** Chip targets exactly one machine — the FoxAlien
> XE-Ultra 8080 (840 × 840 × 120 mm, GRBL/grblHAL over USB serial). Machine
> limits live in config so contributors can adapt it, but nothing else has
> been tested. If you have a different machine, expect to do some work.

## Requirements

- **Windows installer:** Windows 10/11, nothing else needed.
- **pip install:** Python 3.12–3.14 on Windows, macOS, or Linux.
- **Machine control:** the CNC connects over USB serial (CH340/FTDI/CP210x).
  On Linux, add yourself to the `dialout` group to access the port.
- **AI design (optional):** an [Anthropic API key](https://console.anthropic.com/).
  Everything except "design it for me from a sentence" works without one.

## Install

**Windows:** download `ChipSetup-<version>.exe` from the
[latest release](https://github.com/brettbergin/chip/releases) and run it.
Windows SmartScreen will warn about an unknown publisher — click **More info →
Run anyway** (the exe is unsigned; this is expected).

**Any OS, via pip:**

```bash
pip install chip-cnc        # add 'chip-cnc[trace]' for picture tracing
chip                        # launches the app
chip --demo                 # full app with a simulated machine, no hardware needed
chip --self-check           # verifies the install, exits 0 when healthy
```

**With uv** (isolated install, no venv management):

```bash
uv tool install chip-cnc                   # or: uv tool install "chip-cnc[trace]"
chip --demo

uvx --from chip-cnc chip --demo            # or just try it, nothing installed

uv tool upgrade chip-cnc                   # later
```

**With pipx:**

```bash
pipx install chip-cnc                      # or: pipx install "chip-cnc[trace]"
chip --demo

pipx run --spec chip-cnc chip --demo       # one-off run without installing

pipx upgrade chip-cnc                      # later
```

Chip needs Python 3.12–3.14; if your default interpreter is something else,
add `--python 3.14` to the `uv tool install`, or
`--python python3.14` to `pipx install`.

The PyPI package is `chip-cnc`; the import package is `chip`. The `[trace]`
extra (turning photos/logos into carvable shapes) depends on a native
tracing wheel that is broken on some platform/Python combinations; when it
doesn't work, that one feature grays out and everything else is unaffected
(a `potrace` binary on your PATH also works as a fallback).

## First run

1. **Connect the machine** (or don't — `chip --demo` runs everything against
   a simulator). With exactly one known USB-serial adapter plugged in, Chip
   connects automatically; the status strip at the bottom turns green when
   it's ready. If you have several serial devices, pick the port once in the
   Admin area.
1. **Set up the AI designer (optional).** Press **Ctrl+Shift+A** to reveal
   the hidden Admin area, paste your Anthropic API key under *General*, and
   it's stored in your OS keyring. The model is configurable there too.
   Without a key, the "describe it" step offers templates instead.
1. **Make something.** *Make something new* → type a sentence → adjust the
   preview → pick your wood and board size → follow the checklist → set the
   start point → hold *Start carving*.

Everything technical (serial port override, feeds/speeds tables, jog-arrow
flipping for mirrored wiring, raw machine console, logs) lives in that same
Admin area. If something goes wrong and you want help, Admin → *Console &
Logs* → **Export help bundle** zips the logs, the last job, and the design
into one file you can attach to a
[GitHub issue](https://github.com/brettbergin/chip/issues).

Your projects live in the standard per-user app-data directory
(`%LOCALAPPDATA%\Chip` on Windows, `~/Library/Application Support/Chip` on
macOS, `~/.local/share/Chip` on Linux) and autosave continuously — there is
no save button, and deleted projects sit in a trash for 90 days.

## Safety disclaimer

CNC machines spin sharp tools with real force and can injure you and destroy
material. Chip adds software interlocks, but **you** are responsible for safe
operation: eye protection, dust control, secure clamping, and never leaving a
running machine unattended. The software is provided **as-is**, without
warranty of any kind, per the [Apache-2.0 license](LICENSE).

## Development

Chip uses [hatch](https://hatch.pypa.io/) — it creates the environment and
installs all dependencies on first run:

```bash
git clone https://github.com/brettbergin/chip
cd chip
pip install hatch
hatch run test                            # full test suite (Qt runs offscreen)
hatch run lint                            # ruff
hatch run typecheck                       # mypy
hatch run python -m chip.app --demo       # run the app from source, simulated machine
hatch build                               # sdist + wheel
```

Prefer a plain venv? `pip install -e ".[dev,trace]"` then `pytest` works the
same. No display is needed for the tests (`QT_QPA_PLATFORM=offscreen` is set
automatically); the machine-control tests run against the bundled `FakeGrbl`
simulator, and hardware-only checks are documented in
[tests/HARDWARE.md](tests/HARDWARE.md). If you change the design templates,
regenerate the golden files with `python tests/test_golden.py --regen`.

The architecture in one line: `pipeline/` (geometry, CAM, G-code), `models/`,
`store/`, and the GRBL protocol code are pure Python (no Qt) and
headless-testable; `ui/` imports everything; nothing imports `ui/`. A test
enforces this. See [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules
and [DECISIONS.md](DECISIONS.md) for the judgment-call log.

Releases are automated: maintainers tag `vX.Y.Z`, CI builds and publishes to
PyPI (trusted publishing) and attaches the Windows installer to the GitHub
release. There is no manual publish step.

## License

Apache-2.0 — see [LICENSE](LICENSE).
