mirror of
https://github.com/storytold/craft-ai-integrations.git
synced 2026-11-02 18:06:49 +00:00
skylar taylor-barrick
0e55340771
* refactor(ai-egui): migrate shared widgets to egui 0.37 * egui037: qualify shared AI widgets and downstream dependency pins * docs(ai-egui): record the committed migration qualification * fix(ci): provide Vulkan snapshots and allow pinned fork sources * test: make cancellation-before-load coverage deterministic
73 lines
4.9 KiB
Markdown
73 lines
4.9 KiB
Markdown
# Layout: what lives where
|
|
|
|
This repository is the runtime half of the shared AI layer for the Craft apps: one connection, set up once, used by
|
|
every app that has the tool. It owns connections, models, the tool to model binding, the picker
|
|
data, consent and jobs. It does not own any app's interface. Each app decides how a tool looks
|
|
(a prompt bar, a one-click button, a click on the image), in its own repository.
|
|
|
|
## In this repository
|
|
|
|
| Group | Crates | Owns |
|
|
|---|---|---|
|
|
| Core | `ai-core`, `ai-native`, `ai-client`, `ai-features` | The data model and provider trait (wasm-safe), secret stores, the shared store and its location, history and consent files, the app-facing client and tool desk, the tool catalogue and setup options. |
|
|
| Adapters | `ai-openai`, `ai-bfl`, `ai-vertex`, `ai-artcraft`, `ai-seedance`, `ai-comfyui`, `ai-sam3` | One crate per provider API shape. Each is registered in `ai-client`'s `ProviderFactory`. |
|
|
| HTTP | `ai-http` | The one TLS setting every adapter and downloader uses (the platform's certificate check), and a test that fails if any crate builds an agent without it. |
|
|
| Engines | `ai-engine`, `ai-engine-candle`, `ai-engine-rten`, `ai-engine-burn`, `ai-burn-setup` | Models run on this computer: the runner contract, registry and shared provider (`ai-engine`), and one crate per engine that registers its models (`ai-engine-candle`, `ai-engine-rten` and `ai-engine-burn`, behind `ai-client`'s `candle`, `rten` and `burn` features). `ai-burn-setup` prepares the saved weights Burn reads, once on this computer. A new model or engine never touches an app. |
|
|
| Local runtime | `ai-comfy-env`, `ai-media` | Finding an existing ComfyUI, model sources and checksummed downloads, node packs, and durable media transfer. |
|
|
| Widgets | `ai-egui` | Theme-neutral egui 0.37 widgets (status, consent, progress, connection panel, history, model picker) for apps that have no chrome of their own. See the consumer recipe below. |
|
|
|
|
Crates keep the flat `crates/` folder on purpose. The exact planning checkouts reproduced no app
|
|
dependency on `craft-ai-egui`; recheck any current path consumer before moving a crate.
|
|
|
|
`docs/design/` holds design notes. `docs/STATUS.md` says what is tested and what is open. The deliberate-bug
|
|
scripts are in `tools/mutation/`; everything a script saves goes through `tools/mutation/scrub.py`.
|
|
|
|
## Not in this repository
|
|
|
|
| What | Where it goes |
|
|
|---|---|
|
|
| PhotoCraft's Select subject panel, Generate bar, `ai_cmds`, hover session | `storytold/photocraft`, through its own PR and its maintainers |
|
|
| The launcher's Set up AI window, History page and ports | `storytold/craft-launcher` |
|
|
| LightCraft's, EffectCraft's and any other app's adapter | That app's repository |
|
|
| Anything that draws a toolbar or prompt bar | The app. The shared crates never do. |
|
|
|
|
The shared code knows an app only as an `AppId` string and as data in the catalogue's `uses`
|
|
list. If a change here needs to name an app's behaviour, it belongs in the app.
|
|
|
|
## How an app uses this
|
|
|
|
1. Declare a role with the tool's id (the catalogue's `Feature::role()`), for example
|
|
`select-subject`. Do not invent an id of your own.
|
|
2. Call `AiClient::status` to grey the tool out, or to say that a model is needed. Never report a
|
|
tool with no model as broken.
|
|
3. Depend on a pinned git revision (a tag on `main`), not a path. Path dependencies are for local
|
|
work only and must go before an app PR.
|
|
4. A person's choice made for the whole suite is `ToolDesk::choose` (the default every app reads).
|
|
`AiClient::bind` is that one app's own override.
|
|
|
|
## Using the shared egui widgets
|
|
|
|
`craft-ai-egui` is optional and has no app adopter in this repository. An egui app repeats the
|
|
complete `[patch.crates-io]` recipe in its own root; this repository's patch is not inherited.
|
|
The reviewed graph is `storytold/egui` at `6d518fc799681571963842f95b55a6b68431b15a` and
|
|
`storytold/winit` at `a517b3846ee8457d84ee4975110bfda6797c44dc`. Keep the library at
|
|
`default-features = false` for fonts and let the app choose its font provider (or eframe's
|
|
bundled fonts). Do not combine this workspace's `craft-ai-core` with the separate copy in
|
|
`craft-libs`; the [consumer smoke](../consumer-smoke/README.md) shows the one-identity check and
|
|
passes its locked check and one draw test. That headless result is not native GUI acceptance.
|
|
|
|
## Branches
|
|
|
|
- `main` is a state that builds and passes its tests. Apps pin tags on it.
|
|
- Work happens on short-lived branches off `main` and returns by pull request. A merged branch is
|
|
deleted, local and remote.
|
|
- Review that matters happens at the boundaries: the shared contract in `craft-libs`, and each app
|
|
in its own repository.
|
|
|
|
## Rules that apply to every change
|
|
|
|
Test first. A deliberate-bug check for safety rules, with no survivor ignored. Cargo targeted with
|
|
`-p`, one process at a time, `-j 8`; no workspace-wide builds. Files under 500 lines. Nothing runs
|
|
against a real provider, download or ComfyUI without an explicit go. Say plainly what was run and
|
|
what was not.
|