fastbuild123 0.1.0__tar.gz

fastbuild123-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

fastbuild123-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

fastbuild123-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devon Peroutky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastbuild123-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: fastbuild123
+Version: 0.1.0
+Summary: Turn build123d models into  live, interactive parametric web UI
+Project-URL: Homepage, https://github.com/devonperoutky/FastBuild123
+Project-URL: Repository, https://github.com/devonperoutky/FastBuild123
+Project-URL: Issues, https://github.com/devonperoutky/FastBuild123/issues
+Author-email: Devon Peroutky <devonperoutky@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: fastbuild/static/vendor/LICENSE-three-cad-viewer
+Keywords: 3d,build123d,cad,modeling,opencascade,parametric
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: annotated-types>=0.6
+Requires-Dist: build123d>=0.8.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: ocp-tessellate>=3.4
+Requires-Dist: pydantic>=2
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: watchfiles>=1.1.1
+Description-Content-Type: text/markdown
+
+# FastBuild123
+
+Turn any [build123d](https://github.com/gumyr/build123d) model into a live, interactive
+parametric web UI. Annotate your part function's parameters with a FastAPI-style
+`@app.part()` decorator and get auto-generated sliders in the browser with instant
+3D preview — the type-annotated signature *is* the UI definition.
+
+## Quick start
+
+Run a bundled example without installing anything:
+
+```bash
+uvx fastbuild123 demo enclosure
+```
+
+Or install it into your own project:
+
+```bash
+uv add fastbuild123      # or: pip install fastbuild123
+fastbuild view my_model.py
+```
+
+A browser page opens with parameter controls on the left and a live 3D view on the
+right. Drag a slider or save the file — the model updates in place, keeping your
+camera pose, tree state, and clipping planes. A model that raises keeps the last-good
+geometry on screen with an error banner; fix the file and it recovers.
+
+## Defining parts
+
+```python
+from typing import Annotated, Literal
+from build123d import Part, Box
+from fastbuild import App, Group, Range
+
+app = App()
+
+@app.part()
+def enclosure(
+    width:  Annotated[float, Range(20, 200, step=1, unit="mm")] = 80,
+    wall:   Annotated[float, Range(0.8, 5, step=0.1, unit="mm")] = 2,
+    ribs:   Annotated[int, Range(0, 8), Group("Ribs")] = 4,
+    vented: bool = False,
+    style:  Literal["rounded", "chamfered"] = "rounded",
+) -> Part:
+    ...
+```
+
+Widget mapping: `float`/`int` + `Range` → slider, bare numbers → number input,
+`bool` → checkbox, `Literal`/`Enum` → dropdown. Every parameter needs a default —
+defaults are the initial build. Multiple `@app.part()` functions in one file get a
+part selector. Add `Group("Label")` to a parameter's annotation to place it under
+a named collapsible section in the panel; ungrouped parameters render first.
+
+## Headless export
+
+```bash
+fastbuild export my_model.py enclosure --param width=120 -o enclosure.step
+```
+
+Values are validated against each parameter's `Range`; output format follows the
+extension (`.step`/`.stp`/`.stl`).
+
+## Requirements
+
+Python 3.10–3.13 on macOS (Apple Silicon or Intel), Linux (glibc 2.31+, x86-64 or
+aarch64), or 64-bit Windows — wherever `cadquery-ocp` publishes wheels. Expect a
+~500 MB install; the OpenCASCADE kernel is most of it. Alpine/musl is not supported.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run fastbuild demo enclosure
+```
+
+Examples live in `fastbuild/examples/` so they ship with the package and stay
+runnable via `fastbuild demo`. Specs live in `specs/`. The 3D component is a
+vendored, pinned build of
+[three-cad-viewer](https://github.com/bernhard-42/three-cad-viewer)
+(`fastbuild/static/vendor/`, see `VERSION` there) fed by
+[ocp-tessellate](https://github.com/bernhard-42/ocp-tessellate) output over a
+versioned websocket protocol.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Bundles three-cad-viewer (MIT), whose license is
+included at `fastbuild/static/vendor/LICENSE-three-cad-viewer`.

fastbuild123-0.1.0/README.md

@@ -0,0 +1,88 @@
+# FastBuild123
+
+Turn any [build123d](https://github.com/gumyr/build123d) model into a live, interactive
+parametric web UI. Annotate your part function's parameters with a FastAPI-style
+`@app.part()` decorator and get auto-generated sliders in the browser with instant
+3D preview — the type-annotated signature *is* the UI definition.
+
+## Quick start
+
+Run a bundled example without installing anything:
+
+```bash
+uvx fastbuild123 demo enclosure
+```
+
+Or install it into your own project:
+
+```bash
+uv add fastbuild123      # or: pip install fastbuild123
+fastbuild view my_model.py
+```
+
+A browser page opens with parameter controls on the left and a live 3D view on the
+right. Drag a slider or save the file — the model updates in place, keeping your
+camera pose, tree state, and clipping planes. A model that raises keeps the last-good
+geometry on screen with an error banner; fix the file and it recovers.
+
+## Defining parts
+
+```python
+from typing import Annotated, Literal
+from build123d import Part, Box
+from fastbuild import App, Group, Range
+
+app = App()
+
+@app.part()
+def enclosure(
+    width:  Annotated[float, Range(20, 200, step=1, unit="mm")] = 80,
+    wall:   Annotated[float, Range(0.8, 5, step=0.1, unit="mm")] = 2,
+    ribs:   Annotated[int, Range(0, 8), Group("Ribs")] = 4,
+    vented: bool = False,
+    style:  Literal["rounded", "chamfered"] = "rounded",
+) -> Part:
+    ...
+```
+
+Widget mapping: `float`/`int` + `Range` → slider, bare numbers → number input,
+`bool` → checkbox, `Literal`/`Enum` → dropdown. Every parameter needs a default —
+defaults are the initial build. Multiple `@app.part()` functions in one file get a
+part selector. Add `Group("Label")` to a parameter's annotation to place it under
+a named collapsible section in the panel; ungrouped parameters render first.
+
+## Headless export
+
+```bash
+fastbuild export my_model.py enclosure --param width=120 -o enclosure.step
+```
+
+Values are validated against each parameter's `Range`; output format follows the
+extension (`.step`/`.stp`/`.stl`).
+
+## Requirements
+
+Python 3.10–3.13 on macOS (Apple Silicon or Intel), Linux (glibc 2.31+, x86-64 or
+aarch64), or 64-bit Windows — wherever `cadquery-ocp` publishes wheels. Expect a
+~500 MB install; the OpenCASCADE kernel is most of it. Alpine/musl is not supported.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run fastbuild demo enclosure
+```
+
+Examples live in `fastbuild/examples/` so they ship with the package and stay
+runnable via `fastbuild demo`. Specs live in `specs/`. The 3D component is a
+vendored, pinned build of
+[three-cad-viewer](https://github.com/bernhard-42/three-cad-viewer)
+(`fastbuild/static/vendor/`, see `VERSION` there) fed by
+[ocp-tessellate](https://github.com/bernhard-42/ocp-tessellate) output over a
+versioned websocket protocol.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Bundles three-cad-viewer (MIT), whose license is
+included at `fastbuild/static/vendor/LICENSE-three-cad-viewer`.

fastbuild123-0.1.0/fastbuild/__init__.py

@@ -0,0 +1,5 @@
+from fastbuild.cache.wrap import no_cache
+from fastbuild.params import Group, Range
+from fastbuild.registry import App
+
+__all__ = ["App", "Group", "Range", "no_cache"]

fastbuild123-0.1.0/fastbuild/builder.py

@@ -0,0 +1,98 @@
+"""Build execution: part function → geometry → viewer shape JSON.
+
+Each shape node in the output carries its tree path as `id` — the slot the
+caching layer's provenance keys plug into (SPEC-ui §6).
+
+Meshes are cached by handing `ocp_tessellate` our provenance digest as its
+per-instance cache id instead of letting it hash the shape's serialized bytes
+(SPEC-mesh-caching §3). Its own content hash cannot see through the store's
+`BRepBuilderAPI_Copy`, so a cached child would otherwise re-mesh at full price.
+"""
+
+import traceback
+from dataclasses import dataclass
+from time import perf_counter
+from typing import Any, Mapping, Union
+
+from build123d import Compound
+from ocp_tessellate.cad_objects import OcpGroup, OcpObject
+from ocp_tessellate.convert import numpy_to_buffer_json, tessellate_group, to_ocpgroup
+
+from fastbuild.cache.keys import TAG_ATTR, CacheKey
+from fastbuild.params import to_python
+from fastbuild.registry import PartDef
+
+FB_CACHE_PREFIX = "fb:"
+
+
+@dataclass(frozen=True)
+class BuildOutput:
+    part: str
+    shapes: Mapping[str, Any]
+    timings: Mapping[str, float]
+
+
+@dataclass(frozen=True)
+class BuildFailure:
+    part: str
+    traceback: str
+
+
+BuildResult = Union[BuildOutput, BuildFailure]
+
+
+def _provenance_ids(root: Any, group: OcpGroup) -> tuple[tuple[int, str], ...]:
+    """(instance ref, cache id) pairs, but only when `group` is a flat,
+    name-matching image of `root.children`. Any other structure yields ()
+    and leaves ocp_tessellate's own content hashing in place — the mapping is
+    either exact or absent, so a mesh can never be filed under a sibling's key.
+    """
+    children = tuple(root.children) if isinstance(root, Compound) and root.children else ()
+    objects = group.objects
+    if not children or len(objects) != len(children):
+        return ()
+    ids = []
+    for obj, child in zip(objects, children):
+        if not isinstance(obj, OcpObject) or obj.ref is None or obj.name != child.label:
+            return ()
+        key = getattr(child, TAG_ATTR, None)
+        if isinstance(key, CacheKey):
+            ids.append((obj.ref, FB_CACHE_PREFIX + key.digest))
+    return tuple(ids)
+
+
+def tessellate_to_json(obj: Any, name: str) -> Mapping[str, Any]:
+    group, instances = to_ocpgroup(obj, names=[name])
+    for ref, cache_id in _provenance_ids(obj, group):
+        instances[ref]["cache_id"] = cache_id
+    instance_meshes, shapes, _id_map = tessellate_group(group, instances)
+    return numpy_to_buffer_json({"instances": instance_meshes, "shapes": shapes})
+
+
+def build_part(part_def: PartDef, values: Mapping[str, Any]) -> BuildResult:
+    """Build the part and return the result. Caching is engaged iff
+    `harness.install_cache` wrapped the model's functions."""
+    call_args = {
+        spec.name: to_python(spec, values[spec.name])
+        for spec in part_def.params
+        if spec.name in values
+    }
+    start = perf_counter()
+    try:
+        result = part_def.fn(**call_args)
+    except Exception:
+        return BuildFailure(part=part_def.name, traceback=traceback.format_exc())
+    built = perf_counter()
+    try:
+        shapes = tessellate_to_json(result, part_def.name)
+    except Exception:
+        return BuildFailure(part=part_def.name, traceback=traceback.format_exc())
+    done = perf_counter()
+    return BuildOutput(
+        part=part_def.name,
+        shapes=shapes,
+        timings={
+            "build_ms": round((built - start) * 1000, 1),
+            "tessellate_ms": round((done - built) * 1000, 1),
+        },
+    )

fastbuild123-0.1.0/fastbuild/buildloop.py

@@ -0,0 +1,75 @@
+"""Build scheduling: one coalescing queue plus a trailing-edge drag debouncer.
+
+At most one build runs at a time and at most one is pending; a newer request
+replaces the pending one (newest wins). Drag events fire the queue at most
+once per debounce window, reading the freshest state at fire time.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Mapping
+
+
+@dataclass(frozen=True)
+class BuildRequest:
+    part: str
+    values: Mapping[str, Any]
+
+
+class BuildQueue:
+    def __init__(self, execute: Callable[[BuildRequest], Awaitable[None]]) -> None:
+        self._execute = execute
+        self._pending: BuildRequest | None = None
+        self._worker: asyncio.Task | None = None
+
+    @property
+    def busy(self) -> bool:
+        return self._worker is not None and not self._worker.done()
+
+    def submit(self, request: BuildRequest) -> None:
+        self._pending = request
+        if not self.busy:
+            self._worker = asyncio.get_running_loop().create_task(self._drain())
+
+    async def _drain(self) -> None:
+        while self._pending is not None:
+            request = self._pending
+            self._pending = None
+            await self._execute(request)
+
+    async def join(self) -> None:
+        while self._worker is not None and not self._worker.done():
+            await asyncio.shield(self._worker)
+
+
+class TrailingDebounce:
+    """Coalesces a burst of touches into one action per window, trailing edge."""
+
+    def __init__(self, delay_s: float, action: Callable[[], None]) -> None:
+        # window length
+        self._delay_s = delay_s
+        # What to do when window closes
+        self._action = action
+        self._handle: asyncio.TimerHandle | None = None
+
+    def touch(self) -> None:
+        """User drag(s) slider, start debounce window"""
+        if self._handle is None:
+            self._handle = asyncio.get_running_loop().call_later(
+                self._delay_s, self._fire
+            )
+
+    def flush(self) -> None:
+        """User released the slider. Immediatly close window and call action"""
+        self.cancel()
+        self._action()
+
+    def cancel(self) -> None:
+        if self._handle is not None:
+            self._handle.cancel()
+            self._handle = None
+
+    def _fire(self) -> None:
+        """Run the action and close the window"""
+        self._handle = None
+        self._action()

fastbuild123-0.1.0/fastbuild/cache/__init__.py

@@ -0,0 +1,11 @@
+"""Provenance-keyed memoization for model-file functions (SPEC-caching Phase 1).
+
+`keys` and `analysis` are pure; `store` isolates the mutable cache; `wrap`
+builds the memoizing wrappers that `harness.install_cache` installs.
+"""
+
+from fastbuild.cache.keys import CacheKey
+from fastbuild.cache.store import FrozenStats, Store
+from fastbuild.cache.wrap import no_cache
+
+__all__ = ["CacheKey", "FrozenStats", "Store", "no_cache"]

fastbuild123-0.1.0/fastbuild/cache/analysis.py

@@ -0,0 +1,168 @@
+"""AST call-closure analysis: what source a function's key must cover, and
+whether it is safe to cache at all. Pure — findings come back as data.
+
+Cacheability is a property of the transitive closure, not the node: a cached
+caller's hit short-circuits every callee, so impurity, unresolvable calls and
+`@no_cache` are all contagious upward over the same closure the source hashes
+traverse (SPEC-caching §3 Analysis).
+"""
+
+import ast
+import builtins
+import hashlib
+from dataclasses import dataclass
+from typing import Mapping
+
+IMPURE_NAMES = frozenset(
+    {"open", "import_svg", "import_step", "environ", "random", "time", "input"}
+)
+
+_BUILTIN_NAMES = frozenset(dir(builtins))
+
+
+@dataclass(frozen=True)
+class FunctionNode:
+    name: str
+    source_hash: str
+    callees: frozenset[str]
+    impure: tuple[str, ...]
+    unresolved: tuple[str, ...]
+    no_cache: bool
+
+
+@dataclass(frozen=True)
+class Cacheability:
+    closure_hash: str
+    reasons: tuple[str, ...]
+    members: tuple[str, ...]
+
+    @property
+    def cacheable(self) -> bool:
+        return not self.reasons
+
+
+def _assigned_names(node: ast.stmt) -> tuple[str, ...]:
+    match node:
+        case ast.Assign(targets=targets):
+            return tuple(
+                target.id for target in targets if isinstance(target, ast.Name)
+            )
+        case ast.AnnAssign(target=ast.Name(id=name)) | ast.AugAssign(
+            target=ast.Name(id=name)
+        ):
+            return (name,)
+        case _:
+            return ()
+
+
+def _imported_names(node: ast.stmt) -> tuple[str, ...]:
+    match node:
+        case ast.Import(names=names):
+            return tuple(a.asname or a.name.split(".")[0] for a in names)
+        case ast.ImportFrom(names=names):
+            return tuple(a.asname or a.name for a in names)
+        case _:
+            return ()
+
+
+def _has_no_cache_decorator(fn: ast.FunctionDef) -> bool:
+    return any(
+        isinstance(d, ast.Name)
+        and d.id == "no_cache"
+        or isinstance(d, ast.Attribute)
+        and d.attr == "no_cache"
+        for d in fn.decorator_list
+    )
+
+
+def _classify_calls(
+    fn: ast.FunctionDef, functions: frozenset[str], external: frozenset[str]
+) -> tuple[frozenset[str], tuple[str, ...]]:
+    callees: set[str] = set()
+    unresolved: list[str] = []
+    for node in ast.walk(fn):
+        if not isinstance(node, ast.Call):
+            continue
+        match node.func:
+            case ast.Name(id=name) if name in functions:
+                callees.add(name)
+            case ast.Name(id=name) if name in external or name in _BUILTIN_NAMES:
+                pass
+            case ast.Name(id=name):
+                unresolved.append(f"call to '{name}' cannot be resolved")
+            case ast.Attribute():
+                pass
+            case _:
+                unresolved.append("dynamic call target")
+    return frozenset(callees), tuple(unresolved)
+
+
+def analyze_functions(
+    source: str, source_hashes: Mapping[str, str]
+) -> Mapping[str, FunctionNode]:
+    """One node per top-level function, with its resolved model-file callees."""
+    tree = ast.parse(source)
+    defs = [n for n in tree.body if isinstance(n, ast.FunctionDef)]
+    functions = frozenset(d.name for d in defs)
+    external = frozenset(
+        name
+        for stmt in tree.body
+        for name in (*_imported_names(stmt), *_assigned_names(stmt))
+    ) - functions
+    nodes = {}
+    for fn in defs:
+        callees, unresolved = _classify_calls(fn, functions, external)
+        impure = tuple(
+            sorted(
+                {
+                    node.id
+                    for node in ast.walk(fn)
+                    if isinstance(node, ast.Name) and node.id in IMPURE_NAMES
+                }
+            )
+        )
+        nodes[fn.name] = FunctionNode(
+            name=fn.name,
+            source_hash=source_hashes.get(fn.name, ""),
+            callees=callees,
+            impure=impure,
+            unresolved=unresolved,
+            no_cache=_has_no_cache_decorator(fn),
+        )
+    return nodes
+
+
+def _closure(nodes: Mapping[str, FunctionNode], root: str) -> tuple[str, ...]:
+    seen = {root}
+    stack = [root]
+    while stack:
+        for callee in nodes[stack.pop()].callees:
+            if callee not in seen:
+                seen.add(callee)
+                stack.append(callee)
+    return tuple(sorted(seen))
+
+
+def resolve(
+    nodes: Mapping[str, FunctionNode],
+    extra_no_cache: frozenset[str] = frozenset(),
+) -> Mapping[str, Cacheability]:
+    """Fold each function's transitive closure into its hash and its verdict."""
+    out = {}
+    for name in nodes:
+        members = _closure(nodes, name)
+        digest = hashlib.sha256(
+            "\n".join(f"{m}:{nodes[m].source_hash}" for m in members).encode()
+        ).hexdigest()
+        reasons = []
+        for member in members:
+            node = nodes[member]
+            via = "" if member == name else f" (via '{member}')"
+            reasons.extend(f"impure name '{n}'{via}" for n in node.impure)
+            reasons.extend(f"{u}{via}" for u in node.unresolved)
+            if node.no_cache or member in extra_no_cache:
+                reasons.append(f"@no_cache{via}")
+        out[name] = Cacheability(
+            closure_hash=digest, reasons=tuple(reasons), members=members
+        )
+    return out