๐ช Adapt Recipe and ๐ฒ Variations
Adapt Recipe is a separate AI use case. It never edits the source recipe; it creates a reviewable draft, which the user can save as a distinct recipe with a new ID. Saved Recipe IDs are based on the final reviewed recipe name, using the same readable lowercase, underscore-separated IDs as manual recipes (for example, dairy_free_oat_bake). If that ID already exists within the organization, Blackcap adds _2, _3, and so on, including when the older recipe is archived or held. This also applies to Bulk Adapt and Combine Recipes; the original recipe relationship is retained independently. Existing Recipe IDs are never automatically renamed.
AI configuration
On AI Configuration, enable Adapt Recipe and assign an enabled provider/model to the intended Economy, Standard or Enhanced Quality Profiles. This use case is disabled by default following migration 257. It uses AI Seeds, usage evidence, and durable jobs. Generation is chargeable when a valid response is delivered even if the user does not later save the reviewed draft. Application or provider failures use standard Blackcap Seed release rules.
Creating an adaptation
Open Recipe Library and choose ๐ช Adapt Recipe from the recipe action drawer, or from the compact action footer of a linked recipe Quick View. Alternatively, drag the thumbnail of Recipe A onto Recipe B in the Saved Recipes list to open single Adapt Recipe with B as the original and A preselected in Combine with Another Recipe. This works in flat and Cookbook Category views, including recipes that cannot be added to the shopping cart. Dragging a recipe onto itself does nothing. Dragging an eligible recipe into the Recipe Cart still adds it to the cart. The drop only opens the dialog: normal Quality Profile selection, two-step AI Seed approval, comparison and save are unchanged. The dialog starts with the existing recipe name/description, and shows the original thumbnail. The Dietary Preferences summary and ๐ฅ Change dialog use the same organization catalog, selection controls, badges and custom note as AI Plan Meals. Overrides affect only this operation and do not edit organization defaults. Enter additional guidance, choose a Quality Profile and AI Seed funding source, then generate. The quality and funding selectors use the same two-column cards, Seed availability display, disabled insufficient-balance state, cost preview, and explicit charge confirmation as Generate Recipe Image. Switching the quality or funding source resets the charge confirmation. The Close button is content-width and the Adapt Recipe dialog itself is the only vertical scroll container; the header stays visible while scrolling. The dietary preferences Change dialog is a separate modal with its own scrolling. Review ingredient quantities, full instructions, servings, changed ingredients, andโwhen source nutrition existsโthe AI-estimated revised nutrition before saving. The AI also reviews source preparation/cooking/total times and cleanup rating, retaining them unless the adaptation justifies a change. Reviewers can adjust those numeric estimates before saving; Blackcap computes Time & Effort from the final adapted recipe, rather than adopting an arbitrary AI rating. Closing or reloading does not discard a queued/running job or a completed-but-unsaved draft. Reopening ๐ช Adapt Recipe on that source automatically restores the latest unresolved job from Blackcap's durable database and shows progress or the review. ๐ Retry explicitly discards the previous review, returns to generation settings, and requires a new AI Seed confirmation for a separate request. ๐พ Save as New Recipe finalizes the review and creates the new recipe; the next Adapt Recipe opening starts fresh. A failed/cancelled job allows a new generation. The same request cannot be billed twice by repeated Generate clicks while an unresolved job exists.
Every AI-estimated nutrition value displays a trailing *, with * Estimated values below the nutrition section in both Recipe Quick View and the Nutrition popup. Numeric values are stored without the display marker so edits, nutrition parsing, and integrations remain unaffected. Nutrition values are unverified estimates. A modified recipe must be reviewed for allergens, ingredient labeling, cooking safety and cross-contact; AI is not a safety certification. If the source has no usable nutrition, do not derive original nutrition during adaptation.
Recipe Library actions
The three-dot action toggle stays at the far right of the recipe row. Primary actions appear in the panel to its left; clicking โฏ expands that same single row leftward to reveal the additional actions. All icons remain vertically centered in the same attached drawer, with no separate floating secondary row. Click โฏ again, click outside, or press Escape to collapse it. Only one recipe drawer can stay open at a time; smaller viewports use a horizontal overflow fallback within the action drawer.
Relationships and Held originals
Each accepted adaptation has its own recipe ID, content, image asset, nutrition and edit history. The saved recipe_id is based on the final reviewed recipe name, with _2, _3 and so on for collisions within the organization; existing IDs are never renamed. Adaptations and other AI-authored Recipes are not website imports, so they have no source webpage URL or View Source link. original_recipe_id links to the immediate source recipe, not necessarily the oldest ancestor. The original is unchanged. ๐ฒ on an original opens its direct variations (one variation opens directly; multiple show a selector); ๐งฌ on a derived recipe opens the source Quick View. Both badges are compact emoji-only buttons sharing the row beneath the thumbnail with the Nutrition badge. The selector is handled by the reusable Quick View script, not a per-library-render function. Quick View remains focused on reading, and all Quick View contexts have a sticky compact emoji-only action footer with tooltips, excluding Delete and Refresh Cache. The source recipe and adapted recipe share the same centered compact nutrition and relationship badges beneath their thumbnails. A recipe can have multiple variations and be adapted again.
Held means preserved for history while related recipes still exist. A Held original is hidden from normal recipe discovery, but viewable and restorable via a linked Quick View. It is not archived and its files are not deleted. A recipe is eligible for permanent purge only after all direct children have already been purged; nested adaptation families must be purged leaf-first. Adapting a recipe never changes the original's visibility or lifecycle status. Held is applied only when the user deletes an original that still has dependent adaptations. That deletion hides the original while retaining its content, images and direct links. Without adaptations, the normal Archive path is used. A Held source becomes eligible for ordinary retention-based purge once its final dependent adaptation has actually been purged; a Held source can also be restored to the library.
Saved adaptation details and variation cards
The adapted recipe stores a snapshot of the dietary preferences and custom request used for the original adaptation in the recipe's canonical adaptation_metadata_json (organization + recipe-scoped). No additional table or database migration is required. These details are informational, not search filters, and the original recipe remains unchanged. A later edit to these labels does not rewrite the historical AI Usage input/output audit or regenerate the recipe.
The multi-variation selector is titled [Source recipe name] Variations and displays each variation's thumbnail, title, saved description, recipe type/layout, color-coded Total Time, Cleanup, and Time & Effort pills where known, using the same shared configuration/colors as the Recipe Library. It omits cache status, actions, and nutrition/relationship badges. Below the attributes it shows the selected dietary preferences with the same emoji and red-cross-through visual language as the Plan Meals preference selector, plus any custom dietary note or request. Recipe Library cards may show a compact line of the same descriptive context.
Migration 257 also requires the explicit recipes column projection to include its adaptation and Held fields. The canonical organization-scoped API is used to populate Quick View and both editing forms; legacy recipe snapshots are used only when the canonical metadata is empty. These details are independent from the recipe cache and must remain visible after PDF/image rendering.
Quick View is read-only. An adapted recipe has an initially collapsed ๐ช Adaptation Details panel that displays its saved dietary preferences and adaptation request without any editing controls. To update those descriptive tags, use Edit Metadata in Recipe Library or Edit Recipe in the recipe content editor. Both editing surfaces show an initially collapsed Adaptation Details section near the recipe description, with clickable, selectable preference pills (no checkboxes), a custom dietary note, and the adaptation request. Changes are saved through the existing recipe Save buttons; when only adaptation details change, Blackcap updates only that metadata (no โ๏ธ Edited badge, new cache job, or PDF/image rebuild); there is no separate adaptation-details Save button. Cancel leaves changes unsaved. These edits do not modify recipe ingredients, instructions, provider usage records, or the original recipe. Standard recipe edit permissions and organization isolation apply.
Deployment and validation
Migration 257 adds columns and indexes on recipes using Blackcap's migration runner for SQLite and PostgreSQL. No new cron job, standalone worker, or deployment-specific daemon is introduced. Deploy the change using normal full-application or changed-files source package flows after validation on both backends. Review and test permissions, AI provider configurations, image paths, database backup/restore, and durable restart on a staging organization before release.
Generation safeguards and progress
Generate Recipe Adaptation remains disabled unless the user selects at least one dietary preference, enters a temporary custom dietary note, or writes adaptation guidance. The backend enforces the same requirement before creating a durable job or reserving any AI Seeds. The source recipe name and description are prefilled for convenience but do not count as a requested change. A selected Quality Profile, affordable funding source, and spending confirmation remain mandatory.
The durable progress display includes the selected provider name (for example, OpenAI: Adapt recipe) together with Seed reservation, queuing, validation, and review milestones. Reopening an unresolved job shows its persisted progress; it never silently starts or bills for another adaptation.
Variation lookup performance
Migration 257 already creates idx_recipes_org_original on (organization_id, original_recipe_id) and a status-aware composite variant. Do not add duplicate indexes. The Recipe Library batch query now returns the sole variant's recipe ID for direct navigation when there is exactly one child. For multiple children, the indexed relationship endpoint remains authoritative. When Quick View already contains the relationship list, it passes that list into the selector without another fetch. When a lookup is required, the selector immediately displays Loading recipe variationsโฆ instead of appearing unresponsive. After deployment, compare response times on real Pi and PostgreSQL databases before considering further index changes.
Adapted recipe cache behavior
An accepted adaptation uses the Recipe Adaptation source classification and independent manual/editable content, with its own source image and content, not a web recipe to re-scrape. Once the recipe and editable content commit successfully, Blackcap enqueues an editable PDF/PNG cache render through the existing durable recipe-cache queue and serial worker. This avoids a separate renderer thread or extra cron job. A cache enqueue failure is logged and returned as cache_queued=false with a message; the successful recipe save is not rolled back or reported as unsaved. Existing adaptations created before this queueing fix may still lack a tracked cache job and can be recovered with the normal Refresh Cache action on their Recipe Library entries. On Pi, queued work may wait behind an active cache render due to process-wide serialization; use the cache/job status page or existing queue diagnostics to distinguish waiting from a missing job.
AI Usage audit and analysis
Every provider attempt creates an AI Usage event with the normal Seed and provider telemetry. ๐ช Adapt Recipe has a filtered use-case summary (requests, successes, failures, AI Seeds, latency, and System Admin-only estimated provider cost); System Admins can compare Quality Profiles through ๐ Profile Summary. The ๐ฌ Analyze action opens What Happened: the source recipe name, description, complete supplied ingredients/instructions, yield and timing; the selected organization dietary preferences/custom note and explicit adaptation request; and the generated independent draft with change summary, new ingredient/step lists, timing, and estimated nutrition. Failed attempts show the failure reason and any returned draft when present. Evidence is copied from the job's inputs and generated provider response at completion, so later edits to recipes or dietary settings do not rewrite AI history.
These bounded snapshots have the normal AI Usage retention period and are scoped to authorized organizations; raw provider credentials are not stored in the evidence. Generated draft review is a separate operation from saving the new recipe. Previously recorded events lacking full evidence cannot be reconstructed after their retention data is gone.
Bulk Adapt Recipe (0.7.2-alpha design and implementation)
From Recipe Library, a multi-selection action supports a single shared Adapt Recipe request with up to 25 Recipes, subject to provider input/output capacity. One durable provider request produces one AI Usage event and a single AI Seed charge, with a Plan Meals-style base charge, included Recipes, and additional Recipes billed in configurable groups. Show the pricing calculation before funding confirmation, and retain that calculation in AI Usage.
All selected recipes share the dietary preferences and adaptation request, but AI must return a full, independently identifiable result for each source. The response is rejected if source identifiers are duplicated, omitted, or mismatched. The user reviews one result at a time, can save independently, move back and forward between unsaved results with Previous / Next, and use โ Finish Review to explicitly discard remaining unsaved drafts after a summary confirmation. ๐ View Original opens the source recipe, and a saved adaptation immediately advances to the next unsaved result. Saving the final result opens a clear Review complete โ โ Done screen; no additional job download is needed after each successful save. A cache build is durably queued after the save commits, then starts after a short delay to avoid competing with the HTTP response on Pi. Saving an adapted recipe uses Recipe Adaptation as its source classification, while keeping the editable/manual cache format.
The batch's AI Usage analysis shows shared dietary guidance first and then one collapsed section per source recipe. No separate AI Usage charge is created when individual results are saved. This is a 0.7.2-alpha feature; validate the configured provider's context and output capacity with smaller batches before using all 25 recipes. The button and progress labels use Adapt Recipe / Adapt Recipes, including the exact number while the provider is working.
Batch size and incomplete provider responses
The maximum selection remains 25, but not every model/Quality Profile can reliably return that many complete adapted recipes in one structured response. The previous 400-output-token-per-recipe preflight was insufficient for full ingredient lists, steps, optional nutrition, and timing. Blackcap now estimates the output budget from the actual selected recipes, reserves headroom for structured JSON and model reasoning, and shows a profile-specific recommended count. If the selected profile is too small, Adapt Recipes is disabled with a tooltip explaining the allowed count and need for a higher-capacity Quality Profile or a smaller selection. The server enforces the same check before creating a job or reserving AI Seeds. The provider receives a compact source snapshot and explicit expected source IDs, without redundant image or nutrition display payloads. The capacity estimate is conservative, not a provider guarantee; some models may still omit a recipe.
Responses must still have exactly one adaptation per original. When a provider returns fewer, duplicated, or incorrect IDs, Blackcap rejects the entire batch, releases reserved Blackcap AI Seeds, and creates no recipes. There is no silent second AI request and no partial review. The external provider may still charge for the failed request: released Blackcap AI Seeds are not a refund of external API costs. For very large selections, adapt smaller batches or configure an eligible model/profile with sufficient output capacity.
Recipe source reporting
Newly saved adapted Recipes use the recipe_adaptation source identity, displayed
as Recipe Adaptation in Stats for Geeks, Recipe Library source filters, and
other source-aware views. Migration 260 reclassifies previously saved
adaptations in SQLite and PostgreSQL without changing their file_type=manual
editable rendering. This classification is distinct from Held/Archived status,
and no additional cache rebuild is needed for the reclassification.
Cache safety and display refresh
Adaptation details are durable fields on the canonical recipe record, not generated cache artifacts. The cache worker preserves original_recipe_id, adaptation_job_id, and adaptation_metadata_json across cache-only status/artifact writes. Updating adaptation details through the existing Save buttons is transactional with the recipe database edit; recipe read caches are invalidated after commit. Quick View remains read-only and shows the updated descriptive tags when reopened, reading the canonical organization-scoped recipe data if the runtime/cache projection omits it. A cache rebuild does not rewrite the adaptation request, dietary snapshot, or AI Usage evidence.
Draft actions, progress, and recipe-list updates
- Close preserves an unfinished AI job or unsaved review for later reopening.
- โฉ๏ธ Cancel appears only after generation has completed. It discards the unsaved review and closes the dialog, without running or cancelling a provider request. During generation, use Close to leave the durable job running and resume later.
- ๐ Retry discards a completed unsaved draft and returns to the funding and dietary settings for a separately confirmed AI generation.
- ๐พ Save as New Recipe creates an independent recipe and refreshes Recipe Library's current filtered listing without a browser page reload.
- The progress tracker follows Generate Recipe Image: green checkmark for complete, purple circle for active, and an open circle for upcoming steps. It distinguishes Seed reservation, preparing details, submitting to the provider, provider generation, validation, and review. It appears as soon as submission starts, then reads the durable job during the initial request as well as after submission. A job can be resumed after closing or restarting.
- Home's Recipe List and selected-recipe card, Meal Planner recipe lookup, and kiosk recipe cards display dietary badges and saved adaptation guidance as read-only metadata. Home's lightweight organization-scoped recipe query includes those fields without fetching editable recipe content for every card. Meal Planner lookup tiles grow to fit the longest details in each grid row; the action controls remain below the text. This display metadata does not change search filters or generated PDF/image caches.
Regression coverage
Both standard System Admin Regression Tests and diagnostic-clone regression runs include a live Adapt Recipe flow in their own isolated test organization. Configuration-only diagnostic clones do not run this check. It uses the least-expensive configured real Adapt Recipe Quality Profile, the usual AI Seed reservation/settlement lifecycle, and one short disposable recipe. It verifies that the original recipe remains unchanged until deliberately Held, while the newly saved adaptation owns its content and metadata. This regression makes an actual provider request; account for its provider usage when enabling scheduled regression runs.
๐ Combining Recipes (0.7.3-alpha development)
From single-recipe Adapt Recipe, optionally search the organization Recipe Library for a second Recipe under Combine with Recipe. This option is not present in Bulk Adapt Recipes. The original Recipe remains the primary variant parent. The secondary source is recorded as Combined With in the saved adaptation metadata, without creating a variant under the second source.
The initial Seed calculation has two rows: Compare Recipes and Create Combined Recipe. Reserve both up front. Comparison Seeds settle when the comparison succeeds; final-generation Seeds settle only if the user confirms and a valid final recipe is generated. Canceling an already-completed comparison releases the unused final reservation; ordinary comparison charges remain.
Layer-aware comparison recovery: If the AI describes the flour/egg/buttermilk mixture as a โbatter baseโ and a second recipe uses a bottom pastry shell, Blackcap verifies their actual roles against both source recipes' ingredients and instructions before treating them as mutually exclusive. When the source clearly establishes batter poured over filling and an unbaked bottom pie crust under filling, and both options are individually compatible, the comparison presents Select both with explicit pan, moisture, pastry-protection and doneness guidance. This narrowly scoped repair does not override an incompatible option, missing structural evidence, or dietary overrides. A new comparison is needed to benefit from updated prompts; already completed, saved comparison decisions do not change retroactively. Real AI may still require human review of ingredient ratios and bake methods.
The grouped comparison identifies Choose one selections for mutually exclusive techniques, Select any checkboxes for complementary elements (including a Select both shortcut when two options are compatible), and AI-adjusted preparation notes for baking time, layering and other dependent steps. Optional additions can be left unchecked. For example, the user can combine a pastry shell with a carefully adjusted poured batter topping and add bacon without taking every seasoning from the second recipe. The generation AI reconciles quantities, moisture, doneness and cooking time; it must not copy a source bake time unchanged. The comparison still flags incompatible options, offers alternatives and explains dependencies. Similarity is AI-assisted, not a quality ranking. If all chosen compatible characteristics match one source and neither dietary requirements nor instructions require changes, the user may use that existing Recipe without another generation call. Otherwise review and save a new Recipe. The primary source remains unchanged.
The second source appears under Adaptation Details in Quick View; its link opens another Quick View on top. Verify Seed recovery and all retries against a running installation before enabling production use.
Combine Recipe selection (0.7.3-alpha follow-up)
The optional Combine with Another Recipe section is collapsible. A quick name search and Advanced Recipe Search pop-up allow matching by keyword, ingredient, type and maximum total minutes. The selected recipe can be removed with a content-width button.
Comparison choices may have a single required dietary-compatible alternative when neither source satisfies the restriction; shared traits are informational, not forced into radio groups. Do not invent a second incompatible selection.
A comparison with no compatible choice in a category is rejected rather than silently discarding a dietary restriction.
Selecting complementary attributes (0.7.3-alpha)
Comparison options are typed as single (one option ID), multiple (an array of zero or more compatible option IDs, subject to the comparison's minimum), or automatic (no user selection; preparation guidance carried into generation). Older durable comparisons without these fields continue as single-choice. The compare and generation requests still use the same Adapt Recipe Quality Profile and original two-request Seed reservation. The selection API validates every chosen ID against the stored job, forbids incompatible choices and duplicates, and records exactly what the user chose in AI Usage and adaptation metadata.
The permanent synthetic comparison fixture uses Cheeseburger Pie and Bacon Cheeseburger Pie: independent bacon selection, pastry shell plus buttermilk batter as an eligible joint structure, and automatic adjustment of layering and baking. This tests composition, not provider-specific taste or recipe quality.