๐ค AI in Blackcap
Audience: User, Org Admin, System Admin, Developer Related: Providers And Connections ยท Seeds And Usage ยท Social Import ยท Ai Image Generation ยท Ai
Blackcapโs AI subsystem separates providers, provider connections, use cases, quality/intelligence profiles, prompts, usage reservations, AI Seeds, monthly allotments, reporting, and generated-asset retention. OpenAI, Google Gemini, and Anthropic Claude are implemented provider families, subject to configured credentials and registered capabilities.
Current use cases include recipe image generation, social recipe enhancement/review, recipe-photo extraction, Plan Meal, Plan Meals, Support Chat, and the explicit disabled-by-default Inventory Photo Analysis accelerator. Anthropic Claude is available for structured Support Chat, Recipe Photo, and Plan Meal profiles; image generation remains OpenAI/Gemini and direct social-video review remains OpenAI/Gemini. AI output is reviewed and validated by the feature workflow; it does not replace deterministic source extraction or organization permissions.
For asynchronous AI jobs, Blackcap uses one user-facing progress convention: a persistent list of high-level steps remains visible, completed steps gain check marks, the current step is highlighted, and upcoming steps remain visible. Active work is not repeated in a second spinner/title/status block. Separate status text is reserved for errors, provider-outcome recovery/retry guidance, readiness for user review, or terminal results. Support Chat remains conversational and does not use this job-progress checklist.
Durable and restart-safe AI jobs
Blackcap uses the application database as the authority for AI execution. There is no separate AI worker/systemd service: the existing Gunicorn application processes still run the in-process background work, while expiring database leases ensure that only one process owns a job at a time. Lease owners include an application-generation identity shared by Gunicorn workers in the same Blackcap service run. After a full systemd service restart, the new generation may immediately recover leases left by the prior, now-dead generation instead of waiting for the normal lease timeout; workers in the same generation still respect the active lease and atomic database claim. A recurring recovery sweep also handles ordinary worker crashes after lease expiry. Python thread maps are not relied on for cross-process duplicate prevention.
Every AI job has a durable phase (queued, claimed, provider_submission, provider_pending, response_checkpointed, post_processing, or a terminal/interruption phase). Individual provider calls are stored in AI Job Provider Interactions, which is especially important for Plan Meals because the planning request and each Find & Add/source-acquisition AI interaction can be recovered independently. When a normalized successful provider result is available, Blackcap commits that result and provider usage to the interaction before feature-level post-processing, Seed settlement, Recipe/Meal Slot changes, or image persistence. After that checkpoint, recovery reuses the saved result instead of making another provider request. A checkpoint is a durability boundary, not a billing boundary: AI Seeds settle only after the use case accepts a valid response; otherwise the reservation is returned to its original account.
OpenAI Responses and Gemini models that support background Interactions are submitted as stored/background operations and their provider IDs are recorded for retrieval after restart. If a Gemini model definitively rejects background=true before submission, Blackcap safely retries the same stored Interaction synchronously and checkpoints the returned response without polling it as a background operation. A synchronous provider operation that cannot be retrieved safely, notably Anthropic Claude Messages or a Gemini synchronous fallback interrupted before Blackcap receives its response, is treated more conservatively: a controlled application restart is blocked while it is inside the non-retrievable provider window. If the process dies in that window, the job becomes outcome_unknown; Blackcap does not automatically submit a second provider request, and the reserved AI Seeds are returned because Blackcap did not receive a valid response.
Post-processing is restartable too. Use-case progress is checkpointed, and Plan Meals records slot-level progress so a recovered job does not replay already committed Meal Slots or completed source-resolution work. Support Chat persists the waiting assistant message and durable AI job before returning from its HTTP message request, so the browser can continue polling while the AI work survives a normal application restart.
This document describes the completed Blackcap AI administration experience. It covers platform configuration, organization and personal AI Seed management, organization-scoped usage reporting, the API Tester, Database Admin resources, and regression coverage.
Terminology
The product currency is always written as:
- AI Seed
- AI Seeds
Each AI action shows its AI Seed cost before confirmation. AI Seeds are not Blackcap API Tokens and are not provider input/output/image tokens.
The compact UI identity is ๐ฃ, but bounded monthly organization allotments use the blackcap-fruit fill meter with exact balance text. The fill is always purple. Personal or additional balances do not use a percentage meter unless a meaningful denominator exists.
Administration locations
| Location | Responsibility |
|---|---|
| Configuration โ Platform โ AI | Provider connections, credentials, health, use cases, profiles, models, AI Seed prices, billing identity, and retention settings |
| Administration โ Organizations | Organization monthly allotment, additional balance, reserved amount, total available, balance facets, and System Admin management |
| Organization Details / Current Organization | Organization balance panel; System Admin edit, authorized non-System Admin read-only |
| Administration โ Users | Global personal AI Seed summary; System Admin adjustment, Org Admin read-only where authorized |
| Account | Signed-in user's read-only global personal balance and active-organization balance |
| Administration โ AI Usage | Authorized operational usage reporting and System Admin provider billing reconciliation |
| Administration โ Data Cleanup | Asset-type-aware AI candidate retention and cleanup status |
AI Configuration does not contain duplicate organization/user balance editors or the operational usage table.
Organization AI Seeds
Organization rows show the monthly allotment, percentage remaining, additional non-expiring balance, reservations, total available, or Unlimited for the Default organization. The Organizations page includes server-side balance facets:
- Any balance
- No monthly allotment
- No active monthly period
- Monthly allotment exhausted
- Less than 10% remaining
- Less than 25% remaining
- Has additional AI Seeds
- Has reserved AI Seeds
- Unlimited
The management dialog loads authoritative values and does not calculate the post-save balance in JavaScript. Recent ledger entries are not embedded in the main dialog; ๐ Show Recent Adjustments loads them on demand in a separate dialog.
Monthly anchor changes
Beginning next billing period keeps the current bucket unchanged and applies the new entitlement at the next non-overlapping boundary.
Adjust current period now atomically changes the existing current monthly bucket's period boundaries and configured amount. It preserves spent and reserved amounts and never creates a second overlapping monthly grant. If another bucket already overlaps the requested period, Blackcap rejects and rolls back the change instead of silently adding AI Seeds.
Personal AI Seeds
Personal AI Seeds belong globally to a user and can be spent in any organization where that user is authorized to use AI. Usage still records the organization where spending occurred.
- System Admins can make append-only global personal adjustments with a required reason.
- Org Admins can see the available and reserved global balance for members of organizations they administer, but cannot edit it or see unauthorized cross-organization activity.
- Ordinary users cannot inspect another user's personal balance.
- A System Admin's personal source is unlimited under the current policy.
- The organization source is evaluated independently. Switching organization context shows that organization's real finite/unlimited balance; System Admin status does not make every organization unlimited.
AI Usage page
GET /admin/ai/usage renders the dedicated operational report. It supports authorized organization selection, date range, provider, connection, use case, quality profile, user, result, funding source, estimated provider-cost range, sort, page, and records-per-page filters.
The report uses server-side filtering, counting, aggregation, stable ordering, and paging. Estimated cost and latency can be sorted low-to-high or high-to-low. System Admins can also filter by minimum/maximum estimated provider cost to isolate unusually expensive provider requests.
Filter choices are faceted instead of independent. Selecting an organization narrows the user list to users relevant to that organization while diagnostic-clone and regression-test identities are excluded from the normal User selector. Provider, Connection, and Profile constrain one another so impossible combinations are removed or cleared. Provider rows show the provider name; the actual model used remains available as detail/tooltip rather than repeating the provider and model in the main cell.
Each usage row snapshots the quality-profile display name when possible and records the configured AI Seed usage even when the account/source is unlimited. Unlimited usage therefore contributes to product-consumption reporting while the actual balance debit remains zero. Provider request identifiers and detailed provider token usage remain System Admin-only.
Estimated provider cost is calculated from the best completed-request information available for each use case and a versioned pricing snapshot. It is explicitly an estimate, not invoice-accurate billing. The report shows total estimated provider cost plus grouped Recipe Image, Adapt Recipe, Social Recipe Extraction, Recipe Photo Extraction, Inventory Photo Analysis, Plan Meal, Plan Meals, and Support Chat summaries. The first five use-case summaries use the same request/success/failure, AI Seed, latency, and estimated-cost pattern; Support Chat remains intentionally session/effectiveness-oriented. All summaries follow the current report filters. System Admins also receive a ๐ Profile Summary action for every use-case summary; it preserves the configured profile order and compares the profile's current configured AI Seed price with historical request count, average latency, and average estimated provider cost while ignoring only the report's current profile filter. A System Admin-only header-level โ๏ธ AI Seed Cost Alignment analysis compares non-zero active profiles across use cases. It shows ordinary average estimated cost and uses effective provider cost per successful priced request (including known spend from failed attempts) per configured AI Seed to flag materially higher relative cost exposure for pricing review.
Available row actions include:
- ๐ View support chat for retained Support Chat history;
- ๐ผ๏ธ View generated image while the generated candidate remains retained;
- ๐ฌ Analyze on Recipe Photo, Social Recipe, Inventory Photo Analysis, Plan Meal, Plan Meals, and Adapt Recipe usage, opening What Happened to show retained provider input evidence beside the provider's structured output/review state even if the user never applied it;
- ๐ Copy Provider Request ID for System Admin provider correlation when an identifier was captured.
The What Happened action follows normal AI Usage organization authorization. Estimated provider cost inside row details remains System Admin-only. Social evidence retains the public source URL and textual evidence but never a copy of the social video; the UI provides a best-effort iframe plus a durable open-source link. Recipe Photo evidence retains the bounded provider-prepared image rather than another full-resolution source upload.
JSON API
GET /api/admin/ai/usage returns the same authorized report as safe JSON, including the normalized filters, full-filter summary, grouped use-case summaries, Support Chat effectiveness summary, server-paged rows, paging metadata, and safe filter-option catalogs.
The reporting service removes provider request IDs, provider token counts, provider usage payloads, provider response metadata, and provider-cost details that are not permitted for the current role before the API response is built. Provider credentials and raw prompts are never returned.
Additional read surfaces support AI Usage actions:
GET /api/admin/ai/usage/support-chat/{session_id}returns the authorized retained user-visible Support Chat transcript and trusted documentation links, or reports that history has been purged.GET /api/admin/ai/usage/profile-summary/{use_case_key}is System Admin-only and compares current profile AI Seed pricing with historical average latency/provider cost in the current report scope.GET /api/admin/ai/usage/what-happened/{event_id}returns organization-authorized Recipe Photo/Social Recipe/Inventory Photo Analysis/Plan Meal/Plan Meals/Adapt Recipe input/output evidence. Provider cost is added only for System Admins.GET /api/admin/ai/usage/what-happened/{event_id}/artifact/{artifact_index}serves a retained Recipe Photo evidence image. It is documented but not executable in the text/JSON viewer.GET /api/admin/ai/usage/generated-image/{event_id}serves the authorized retained generated-image binary. It is documented in API Tester route coverage but is not executable in the text/JSON response viewer and is excluded from Postman export.
Reconciliation export
GET /admin/ai/usage/reconciliation.csv is System Admin-only. It uses the same authorized report filters, including the estimated-cost range, and includes provider billing fields, safe request identifiers, normalized provider token counts, retry lineage, AI Seed accounting values, and billing-context metadata. Billing context is retained for reconciliation/export but is intentionally not repeated as a visible AI Usage table column because it is normally constant for one Blackcap instance.
API Tester
The AI Usage category exposes:
- AI Usage Report
- View Support Chat History
- AI Usage Quality Profile Summary (System Admin only)
- AI Usage What Happened
- AI Usage What Happened Photo Artifact (documented binary route; not executable/exported)
- View Retained Generated Image (documented binary route; not executable/exported)
- Download AI Provider Billing Reconciliation CSV
- Organization AI Seed Balance
- Organization AI Seed Recent Adjustments
- Personal AI Seed Balance
The registry remains curated. Safe read operations are executable through the authenticated tester. Reconciliation remains System Admin-only. AI Seed adjustment writes are intentionally not added as automatically safe API Tester operations because they alter audited balances.
Database Admin
Database Admin exposes all 16 AI Database Admin resources covering the AI/support foundation in a System Admin-only AI group:
ai_provider_connectionsai_use_casesai_profilesai_drupe_accountsai_organization_entitlementsai_drupe_bucketsai_jobsai_media_artifactsai_drupe_reservationsai_drupe_ledger_entriesai_generated_image_candidatesai_usage_eventssupport_chat_sessionssupport_chat_messagessupport_chat_message_sourcesai_recipe_image_state
The AI Usage Events resource exposes normalized usage/correlation fields such as cached input, reasoning, estimated provider cost, Support Chat session/message IDs, prompt version, and documentation corpus version while keeping private provider-usage/metadata JSON hidden. Reconciliation additionally exports billing instance/environment, Blackcap client request ID, provider response ID, retry lineage, reservation/entity/support correlations, prompt/corpus versions, all Seed accounting fields, and all normalized token categories when available; retained AI-job/candidate data is used as a compatibility fallback for historical usage rows. Migration 227 adds retained Recipe Photo/Social Recipe evidence JSON and artifact metadata to the AI Usage row, but those private evidence fields are also hidden from generic Database Admin; use the authorized ๐ What Happened viewer instead.
Support Chat database resources are deliberately metadata-oriented. Session page/context JSON, message text/idempotency/private metadata, and documentation content hashes are hidden from generic Database Admin views. Use the authorized AI Usage ๐ transcript action for conversation content. Purpose-built AI pages remain the supported place for normal changes; Database Admin is for inspection and narrowly controlled troubleshooting.
Permissions summary
| Capability | System Admin | Org Admin | Other users |
|---|---|---|---|
| Configure providers/use cases/profiles/prices | Yes | No | No |
| Manage organization AI Seeds | Yes | Read-only for authorized org | No additional access |
| Manage personal AI Seeds | Yes | Read-only for authorized members | Own Account panel only |
| View AI Usage | All or selected org | Administered orgs only | Existing permission model only |
| View Recipe Photo/Social Recipe What Happened evidence | All or selected org | Administered orgs only | No |
| View quality-profile cost/latency summary | Yes | No | No |
| View provider request/token/cost diagnostics | Yes | No | No |
| Download reconciliation CSV | Yes | No | No |
| Inspect AI Database resources | System Admin Database permission | No | No |
Regression coverage
Regression suite 2026.09.02.1 keeps all provider-backed AI regression deterministic: the regression adapters never call OpenAI or Gemini. Support Chat, Recipe Image, social/photo extraction fixtures, and Plan Meal therefore verify Blackcapโs request/accounting/persistence lifecycle without paying for a live model.
The Plan Meal / Letโs Cook Meal phase now covers the recent whole-Meal lifecycle in addition to structured-plan validation and AI Usage correlation. It creates a multi-Recipe + Meal Item fixture, generates one deterministic saved AI Meal Plan, verifies exact one-Seed accounting and What Happened evidence, renames the whole Meal without invalidating the plan, generates/accepts a deterministic AI Meal image through the normal image-job pipeline, verifies Review Plan data plus generated PDF with the custom Meal grouping/image, moves the intact Meal to the same Meal Slot on another date while carrying its custom name/image/current AI plan without another provider call, then verifies planned and sequential Letโs Cook behavior, protected invalidation, explicit replan, and deletion.
The Data Purge phase also creates a historical Meal-domain probe and manually purges it through the same Meal Plans Data Cleanup path used by scheduled retention. It verifies that Meal Plan entries, whole-Meal identity metadata, people-served override, saved AI Meal Plan, and AI Plan Recipe references are removed together. Focused tests remain responsible for exhaustive UI details, timer/provider edge cases, model capability limits, SQLite/PostgreSQL parity, and provider-specific parser behavior.
System Admin tool regression continues to verify API Tester/Database Admin safety and AI Usage privacy boundaries. The Recipe Image phase continues to validate reservation/settlement, configured profile cost, usage recording, generated-image review, and normal Recipe acceptance/cache integration.
Recipe image cache behavior
Selecting or uploading a recipe image continues to use the existing normal cache rebuild workflow. Blackcap does not currently skip PDF/cache work based on the active display's image capability. A future optimization should be render-profile-aware invalidation rather than a blanket skip, because the same recipe may be used by both image-capable and no-image displays.
Database Admin also exposes AI Media Artifacts as the thirteenth AI resource. It shows safe artifact type/size/duration/status fields for social AI troubleshooting while protecting storage paths, hashes, and raw metadata.
More information
- AI Providers and Connections โ Configure OpenAI, Gemini, and Anthropic Claude provider families, connections, use cases, profiles, failure safeguards, and generated-asset retention.
- AI Seeds and Usage โ Understand organization and personal AI Seeds, reservations, settlement, allotments, adjustments, and usage reporting.
- Support Chat โ Documentation-grounded Get Help, bounded conversations, transcript email, and human escalation.
Plan Meals
Plan Meals is the separate multi-date WHAT-to-eat use case. It accepts at most seven selected dates, configured Meal Slot selections, immutable existing Meal content, planning-time Dietary Preferences, an optional Planning Request, and optional compact Kitchen Inventory / Recipe Library context. The default-on Prefer recipes already in the Recipe Library option is distinct from taste preferences: Blackcap loads the organization Recipe evidence once, derives taste evidence when requested, and separately pre-ranks a bounded existing-Recipe candidate catalog (up to 20 per relevant Meal Slot type, deduplicated) with trusted Recipe IDs, category/type/timing/use/rating metadata and optional ingredient names. Missing Made It rating remains unknown/neutral. When 30-day duplicate minimization is enabled, recent Recipe use receives a meaningful pre-provider ranking penalty without becoming a hard exclusion. The Meal Slot chips above the date matrix are the defaults for newly selected days; individual date/slot checks can override those defaults without changing them. Planning Request is free-form guidance for the current runโfor example, Mexican for lunch and pizza for dinner, quick breakfasts, or Italian this weekend. References to a Meal Slot or date apply only to matching selected slots; broader guidance applies across the selected scope. Planning Request never narrows the selected scope: every selected Meal Slot is still planned, and selected slots not mentioned by the request use normal Plan Meals behavior. Blackcap supplies authoritative weekday names alongside ISO dates so requests such as pizza Friday bind to the selected Friday rather than relying on provider date arithmetic. An otherwise-empty selected Meal Slot must receive at least one meaningful addition; Blackcap rejects partial responses instead of silently filling the week with generic local main dishes. Dietary Preferences & Restrictions and immutable existing content take priority, while Blackcap still asks the provider for meaningful dish variety within a requested cuisine/theme. The request is capped at 1,000 characters, retained in the trusted planning snapshot/AI Usage evidence, and participates in the trusted quote fingerprint without changing the Seed pricing curve. Dietary settings start from the organization/household defaults but can be changed for one Plan Meals run without rewriting those defaults. They guide AI planning rather than prohibiting manual Recipe or Meal Planner entry. Plan Meals returns strict structured additions (existing_recipe, recipe_source, recipe_suggestion, or meal_item) and Blackcap validates/reconciles them before any Meal Planner mutation. existing_recipe must use an exact supplied organization candidate ID and is rechecked against the active organization at apply time. Suitable existing Recipes are a strong preference rather than a quota; when Find & Add is also enabled it remains a fallback for new Recipe acquisition. Existing entries are never automatically replaced. The same schema/guidance contract is used for OpenAI, Gemini, and Claude, and request-specific bounds still require exactly every selected Meal Slotโincluding Snack/Dessertโto be returned.
Find & Add prefers grounded Recipe URLs from a web-search-capable provider, but it is not limited to those profiles when server-side Recipe Discovery is configured. Blackcap validates provider URLs against Recipe Search rules and actual capture/acquisition behavior; missing, rejected, or uncapturable URLs fall back per Recipe to Agent Search. Claude and other non-search profiles can therefore use Find & Add through the same fallback without inventing source URLs. Any later capture AI has a separate confirmation/Profile/Seed charge and a separate AI Usage event.
Find & Add source selection is platform-configurable without changing the Gemini/OpenAI/Claude response contract. By default, Blackcap attempts the provider-recommended Recipe URL and bounded alternatives. When Configuration โ Platform โ Recipe Discovery โ Use Recipe Discovery Search for AI Plan Meals is enabled, Blackcap still records every provider-recommended Recipe URL for platform source-site analytics, then evaluates each candidate URL against the active Recipe Search include/exclude rules. An AI-provider URL that is included and not excluded is used directly; only that Recipe candidate falls back to the configured server-side Recipe Discovery search when none of its provider URLs pass. The automated search uses the configured Recipe Discovery result depth and retries once with the Recipe name alone when the name-plus-ingredient-hints search has no preferred result. It prefers non-slow allowed sources and can use an otherwise-valid slow source as a last resort. One Plan Meals response can therefore mix direct provider URLs and Recipe Discovery search results. This keeps provider planning/classification behavior independent from the website-selection policy while avoiding unnecessary duplicate searches. The platform recipe_source_site_stats table separately counts AI Plan Meals recommendations and URL-backed Recipe additions so administrators can identify commonly suggested Recipe domains and decide which sites to add to the curated search configuration.
Plan Meal
Plan Meal moves AI coordination into Meal Planner rather than the moment cooking begins. It accepts a trusted snapshot of one Meal Slot, deterministic Component quantity recommendations and any explicit Component identity/batch override already saved with the dated Meal, optional Serve At, ovens available, and an opt-in temperature-coordination setting. Unresolved Components are included conservatively so the user does not have to decide make/keep or batch timing merely to create the AI plan; those decisions remain provisional through Letโs Cook. The provider returns a versioned structured timeline and Expected Total Meal Time. Blackcap sends an explicit coverage checklist requiring every Recipe/Component source step exactly once and tells the provider to interleave independent work across all Recipes, including parent Recipes while Component work is inactive; only explicit dependencies are hard blockers. Blackcap validates source Recipe/Component/Meal Item IDs, source Recipe steps, ingredient references, Recipe internal ordering, timer references, temperature provenance, required Recipe coverage, and timeline/total-time consistency before saving the plan.
Executing a current saved plan later is deterministic and does not call the provider again. Sequential Meal Slot cooking remains available without AI. Whole-Meal custom names and uploaded/AI-generated Meal images are presentation metadata on the persistent dated Meal identity; changing either does not invalidate the cooking plan. Meal image generation reuses the existing Manual Recipe Image Generation Quality Profiles, AI Seed reservation/settlement, candidate review, and AI Usage lifecycle, but acceptance saves the artifact directly to the Meal rather than waiting for a Recipe edit/save. An intact same-slot date move can carry the current plan and Meal identity when serving inputs remain unchanged.
Create SQL Query
Database Admin's โจ Create Query / Modify Query is an implemented structured-text AI use case for System Admins. It is durable and asynchronous, uses its own Economy/Standard/Enhanced Quality Profiles, and requires an explicit Organization or Personal AI Seed source plus spend confirmation. With an empty SQL editor, Blackcap sends the user's natural-language request and the exact protected-column-safe Markdown schema document produced by Export Schema. Once SQL exists in the editor, the action changes to โจ Modify Query: Blackcap sends the current SQL plus the requested change and links the turn to the prior SQL AI job when available. OpenAI (previous_response_id) and Gemini (previous_interaction_id) can continue their stored provider conversation when the same provider connection/model is selected and the schema fingerprint is unchanged, avoiding retransmission of the full schema on that turn; otherwise Blackcap safely sends the complete original/current/new request context plus the schema again. Gemini documents server-side continuation as a way to improve context caching and reduce token cost. OpenAI continuation reduces the transmitted request size but prior chain input remains billable, so Blackcap also uses a stable schema-based prompt-cache key and keeps the full schema at a stable prompt prefix to improve cached-input reuse on compatible models. Each turn is tracked with a durable chain ID, iteration number, previous job, original request, current SQL, new request, and whether provider-side context was reused. The SQL Console keeps a convenient iteration history for the current browser session and ๐งน Clear resets the editor plus that drafting history; AI Usage remains the durable audit record. The accepted provider response must contain one valid read-only SELECT; Blackcap never executes it automatically and only places it into the SQL Console editor for review. AI Seeds settle only after the response passes SQL validation. AI Usage โ What Happened records the requests, prior/current query context, generated query, iteration linkage, and safe schema/provider metadata. AI SQL profiles use a larger 300,000โ500,000 character full-schema input budget so the live Export Schema document is not constrained by the smaller meal-planning prompt limit; older SQL profiles are normalized to at least 300,000 characters when loaded.
Original Recipe Generation and Combine Recipes (0.7.3-alpha development)
Create Recipe with AI in Recipe Library accepts a description or title, guidance, dietary preferences, Recipe Type and yield. The selected Create Recipe Quality Profile and Seed source are used for a durable generation job. The result is reviewed before saving with the source AI Generated Recipe and no original recipe. The saved Recipe ID is derived from the final reviewed name using the same readable slug and organization-scoped numeric suffix convention as manual recipes. Existing saved IDs are preserved. Estimated nutrition, when available, is marked as estimated.
Combine with Recipe is available only from single-recipe Adapt Recipe. Choose the second Recipe in the same organization, then approve the initial reservation for both comparison and possible final generation. The comparison presents grouped options, compatibility constraints, dependencies and an AI-assisted similarity estimate. Approving a final new recipe is a second, explicit Seed-spend confirmation. If an unchanged existing source Recipe was chosen, the final AI request is skipped.
Create Recipe uses its own create_recipe Quality Profiles; the Combine workflow uses Adapt Recipe profiles for both its comparison and conditional generation. Plan Meals original creation, optional images, durable child recovery and separate provider/Seed usage are implemented. A successful real-provider regression does not replace targeted live tests of every combination or interrupted job.
Create Recipe Quality Profiles (0.7.3-alpha follow-up)
Create Recipe is a separate configured use case (create_recipe), with independent Economy, Standard, and Enhanced Quality Profiles. Migration 263 initializes matching provider selections from enabled Adapt Recipe tiers where available; administrators may then customize these profiles independently. Original recipe AI jobs now use only Create Recipe profiles, and the Recipe Library action is alongside Manual Recipe in Recipe Search. The original-recipe review presents recipe ingredients and instructions, rather than an adaptation difference report.
Optional images for original AI recipes (0.7.3-alpha)
At the Create Recipe review, Generate AI Image opens Blackcap's existing Create Image workflow (manual_recipe_image_generation) using the draft recipe content. Image generation uses its own Quality Profile, funding source, and explicit Seed confirmation; Create Recipe's text-generation Seeds are accounted for separately. After choosing Use This Image, the preview appears in the recipe review and is attached when Save as New Recipe completes. The image remains optional. On Retry, the user explicitly chooses whether to keep the already selected image without spending more image Seeds or replace it (which requires a separately confirmed new image request). Generated-but-unused image charges are not refunded. Both images and original recipe drafts follow their configured retention/review lifecycle; a failed image generation must not overwrite the recipe draft.
0.7.3-alpha โ Plan Meals original Recipe generation
Plan Meals has an optional Create Original Recipes with AI setting with a separate Create Recipe Quality Profile. Max AI recipes per Meal Slot supports 1โ4 (default 1) for eligible slots without an existing Recipe. The high quote includes the planning charge, up to that number of original Recipes per eligible slot, and optional images for every possible new Recipe, alongside any configured Find & Add surcharge. The Plan Meals confirmation authorizes and reserves that maximum once; individual child jobs receive allocations from the parent hold rather than reserving the account again. Only validated planning and actually generated Recipes/images are charged, and unused allocations are released.
Successful original Recipes are saved in the Library and added to their intended Meal Slots; invalid or unsuccessful generations remain Recipe Ideas. The source is AI Generated Recipe with no fabricated website URL or View Source link. Up to the selected 1โ4 original generations are possible per eligible slot, only when normal library reuse/Find & Add did not provide that Recipe. Plan Meals, Create Recipe and Create Image have separate provider/AI Usage entries while using the same confirmed parent hold. The completed Plan Meals dialog reports actual saved original Recipes and Images, plus relevant generation failures.
A Combine Recipes workflow is two metered AI provider interactions but a single What Happened workflow view: Step 1 compares both full source Recipes and dietary/request constraints and returns similarity and selectable characteristics; Step 2 includes comparison results, selected characteristics and the final generated Recipe. The underlying two immutable AI Usage records remain separately auditable for reconciliation and costs.
0.7.3-alpha โ Discover or generate; two-stage usage and optional Plan Meals images
Recipe Discovery now offers โจ Create Recipe in addition to searching external sources. The Create Recipe dialog is shared with Recipe Library, so it uses the dedicated create_recipe use case and its own Quality Profile/AI Seed confirmation. When launched with an unresolved Plan Meals Recipe Idea or a Meal Slot, saving can resolve or assign the created Recipe through an organization-checked route. The resulting recipe has an ai_generated_recipe source; no external recipe URL is invented.
For Combine Recipes, AI Usage retains two separate provider jobs and Seed ledger transactions, and a single What Happened view presents Step 1 (two source recipes, preferences, comparison summary, similarity and choice groups) and Step 2 (user-selected characteristics and final generated Recipe). Retained input/output JSON is accessible through a collapsed technical evidence section. Results are limited by configured AI Usage retention and cannot be restored when provider evidence has been purged.
Plan Meals can generate an image after each successfully generated original Recipe using the existing manual_recipe_image_generation use case. Users must enable this independently and choose a separate image profile. The quote conservatively includes one image for every potentially generated original under the selected 1โ4 per-slot cap. The confirmation reserves the full high estimate once on the parent Plan Meals job, then transfers each actual child job allocation from that hold; only validated work is charged, and unused Seeds are released. Image requests are sequential and idempotent per Meal Slot. Failed optional images leave the Recipe intact and are reflected in Plan Meals result/AI Usage counters.
Plan Meals: optional original recipe and image charging (0.7.3-alpha)
The Plan Meals quote is a maximum: the parent job reserves the entire approved high amount once. Each Create Recipe and optional Create Image child receives its own transfer allocation and settles only actual accepted work, without creating a second account hold. Unused parent allocations are released at completion. Both inline child execution paths use the common durable database lease so a background recovery worker cannot concurrently submit or prematurely release the same job's Seeds. If an image provider outcome is unknown or its Seed reservation was released, do not silently retry; the user must explicitly initiate any new paid request. The What Happened Combine Recipes view exposes source names, descriptions, ingredients, steps, dietary preferences, comparison choices, and generated result with raw JSON retained as optional technical evidence.
0.7.3-alpha UI, provider accounting, and operational checks
- Create Recipe can be launched from Recipe Library or Recipe Discovery, including from an unresolved Meal Planner Recipe Idea. The Meal Planner header no longer has a standalone Create AI Recipe button; the Plan Meals popup continues to offer optional original creation and optional image profiles. Recipe Discovery handles ad hoc creation/assignment for a specific slot.
- The Bulk Adapt Recipe dialog uses the same purple four-column Seed calculation as Plan Meals: pricing component, included/extra Recipes, calculation rule and total. The displayed total is the server-quoted amount and must not be independently re-priced in the browser.
- API Tester provides Create Recipe options/submission/lookup and Compare/Combine confirmation/cancellation. The read-only operations can be assessed for Multi API; provider-generating actions and Seed-release mutations cannot be part of an app-database rollback. See Regression Testing for free contract checks and the live-provider validation checklist.