Audience: User, Org Admin, System Admin, Developer, Support Related: Blackcap Overview · Feature Catalog · AI in Blackcap · AI Providers and Connections · AI Seeds and Usage · AI Troubleshooting

Blackcap uses AI as an optional accelerator inside existing recipe, meal-planning, inventory, image, and support workflows. AI does not replace organization permissions, deterministic source extraction, validation, or user review. A feature must have an enabled AI use case, a usable Quality Profile, a configured provider connection, and any required AI Seed balance before Blackcap offers the corresponding AI action.

This page is the product-level guide to Blackcap's AI capabilities. Detailed provider, accounting, retention, and feature implementation behavior remains in the linked feature documentation.

Current AI use cases

Use case	What it does	Typical result and review
Recipe / Meal Image Generation	Creates an illustrative image from recipe details or a Meal's recipe/item context.	The generated image is validated and shown for review before the user accepts it. Generating another image is a separate AI action.
Social Recipe Extraction	Reviews supported social-source evidence when deterministic extraction alone is not sufficient and an enabled AI profile is available.	Blackcap merges AI-supported extraction with captured evidence and presents recipe candidates or review state rather than treating AI text as unquestioned source truth.
Recipe Photo Extraction	Reviews a recipe photo or screenshot after Blackcap's built-in capture/OCR path has produced the initial recipe candidate.	AI can improve structured title, ingredient, instruction, and related recipe fields. The result is reviewed before replacing the built-in candidate.
Plan Meal	Coordinates at least two plan-worthy Recipe workloads in one Meal Slot into a cooking timeline for a target serve time. Two Recipes qualify, as does one Recipe plus a discovered Component Recipe; Meal Items alone or one Recipe plus Meal Items do not.	Blackcap validates the proposed plan against trusted recipe steps, then saves the accepted Meal Plan for later Let’s Cook use. Planning is optional; cooking the Meal does not require an AI plan.
Plan Meals	Decides what to add across selected Meal Planner dates/Meal Slots (maximum seven dates), using optional Inventory and Recipe Library taste context plus Dietary Preferences prepopulated from the organization/household defaults and temporarily adjustable for that run. Each Meal Slot has a configured Recipe Type that drives existing-Recipe candidate ranking and the Recipe Type assigned when Find & Add creates a new Recipe. Lunch/dinner planning also returns meal-composition coverage and same-response completion candidates so Blackcap can fill a missing vegetable/starch role without another full planning request; if the provider omits or leaves a selected slot blank, Blackcap can make one narrow repair interaction for only the affected slot(s) before AI Seed settlement.	Adds actual Recipes, Meal Items, or durable Recipe Suggestions without replacing existing Meal content. OpenAI, Gemini, and Anthropic use the same conservative Meal Item-versus-Recipe classifier: provider intent is trusted unless Blackcap has strong deterministic evidence to correct it. Find & Add changes source acquisition, not classification. A web-search-capable provider is encouraged to return real Recipe URLs; Blackcap accepts them only when they satisfy Recipe Search rules and can be captured. Missing/rejected/uncapturable URLs—or profiles with no grounded web search—fall back per Recipe to server-side Recipe Discovery (Google Agent Search, Brave Search API, or Tavily Search API), with at most one Recipe automatically resolved per Meal Slot. Recipe Discovery retries a broader name-only query, prefers non-slow sources, and can use a valid slow source as a last resort before leaving a Recipe Idea. Generic captured titles such as `Recipe` yield to the specific planned/search title hint. Any later capture AI requires a separate explicit Seed/Profile confirmation.
Inventory Photo Analysis	Optionally analyzes a kitchen-inventory photo to propose items or package details that would be tedious to enter manually.	Findings are presented for review before inventory is changed. The feature is an accelerator and may be disabled by default depending on the installation.
Support Chat	Uses Blackcap documentation and allowed support context to answer product/support questions conversationally.	The answer stays in the support conversation and can point to relevant documentation or suggest escalation. Support Chat is conversational rather than a staged background-job checklist.

AI-generated Recipe and Meal images share the same image-generation foundation, provider validation, Seed accounting, and review model. Social Recipe, Recipe Photo, Inventory Photo, Plan Meal, and Plan Meals use structured-output validation appropriate to their use case.

What the user sees

Metered AI actions follow one common interaction pattern:

Blackcap shows the available Quality Profiles and the AI Seed cost of the selected profile.
When both funding sources are available, the user chooses Organization AI Seeds or Personal AI Seeds.
The user explicitly confirms spending the displayed AI Seeds. That checkbox authorizes the Seed spend only; provider/privacy information is shown separately.
Long-running AI jobs show a persistent checklist of high-level steps. Completed steps receive check marks, the current step is highlighted, and upcoming steps remain visible.
Normal progress is not duplicated in a second spinner/status block. Separate status text is reserved for failures, recovery/retry guidance, readiness for review, and final results.
Where the feature requires review, Blackcap presents the result before applying it to the durable recipe, Meal, or inventory state.

Changing the Quality Profile or AI Seed source invalidates the prior spend confirmation so the user always approves the cost that will actually be used. Plan Meals additionally requotes when its selected dates/Meal Slots or context options change, because its AI Seed price is calculated from a server-side slot-block curve.

Quality Profiles

A Quality Profile is Blackcap's user-facing choice for the quality/cost level of an AI action. Profiles keep provider-specific details out of ordinary workflows while still allowing System Admins to control which provider, model, capability settings, and AI Seed price back each choice.

A profile belongs to one implemented AI use case. Depending on the provider and use case, it can define or constrain model, reasoning/intelligence level, input/output limits, image resolution or aspect ratio, timeout, media detail, and other provider-specific settings. The configuration dialog exposes these as named fields and provider/model-aware choices rather than requiring administrators to edit miscellaneous provider JSON. Numeric limits show the applicable Blackcap or provider/model maximum when one is defined. Plan Meals labels models that support grounded web search because those profiles can return real Recipe URLs directly. Find & Add Complete Recipes can also run with a non-search model when server-side Recipe Discovery (Google Agent Search, Brave Search API, or Tavily Search API) is configured; Blackcap resolves any missing Recipe URLs after the provider returns the meal intent. Its Quality Profile editor has a dedicated AI Seed Pricing section for base Seeds, included Meal Slots, additional-slot block size, Seeds per block, and the Find & Add surcharge, with a live workload preview. Placeholder use cases remain visible for roadmap/configuration awareness but do not offer Quality Profiles until their runtime is implemented.

Profiles can be enabled, disabled, ordered, and given friendly names such as Economy, Standard, Enhanced, or installation-specific alternatives. The exact profile names and models are configuration, not hard-coded product promises. If a profile repeatedly fails, Blackcap can surface or apply the configured failure-governance behavior rather than silently continuing to spend against a broken option.

See AI Providers and Connections for provider/model capability details.

AI Seeds and funding

AI Seeds are Blackcap's product credits for AI features. They are not Blackcap API Tokens and are not the same as provider input/output tokens.

Organization AI Seeds are shared within the active organization according to its entitlement and balance.
Personal AI Seeds belong to the signed-in user and can be available across organizations the user can access.
A metered operation reserves the configured Seed amount before provider work, commits the charge when appropriate, and releases or reconciles the reservation when the operation fails or is abandoned.
Unlimited funding still records the configured Seed usage so AI Usage can compare Blackcap usage with provider cost even when no finite balance is debited.
Support Chat may be configured at zero AI Seeds while still recording provider usage.

See AI Seeds and Usage for entitlement, reservation, adjustment, and retention details.

AI Usage and What Happened

Blackcap records AI activity centrally so administrators and authorized users can understand what was requested and what happened without relying on provider dashboards alone. Depending on the provider and use case, AI Usage can include:

use case and Quality Profile;
provider and model;
organization/user context allowed by the reporting permission;
selected AI Seed source and reserved/committed Seed amount;
provider-reported input, output, reasoning, image, or other token/usage data when available;
estimated or recorded provider cost when Blackcap has the required pricing data;
provider request/interaction identifier when the provider returns one;
completion/failure category and a user-friendly failure reason;
retained evidence or generated assets where that use case intentionally supports them.

What Happened / Analyze views use the recorded AI Usage evidence to explain the interaction without changing the underlying result. Provider identifiers are captured whenever the provider supplies a request, response, or interaction identifier that Blackcap can safely retain.

The AI Usage page also provides use-case summaries and authorized reconciliation/reporting views. See AI Seeds and Usage for detailed reporting behavior.

How Blackcap talks to AI providers

At a high level, the request path is:

Blackcap feature
  → registered AI use case
  → selected Quality Profile
  → configured provider connection
  → provider adapter
  → provider API
  → Blackcap validation / normalization
  → review or accepted feature result
  → AI Usage and Seed settlement

The provider adapter is the boundary between Blackcap's feature code and provider-specific APIs. Blackcap currently supports configured OpenAI, Google Gemini, and Anthropic Claude provider families where the chosen model and adapter declare the capabilities required by that use case. Not every provider/model is expected to support every Blackcap AI feature.

Provider credentials are protected configuration and are never returned to normal user-facing AI screens. Blackcap sends only the feature context needed for the selected operation, subject to that feature's documented behavior. The feature workflow remains responsible for organization authorization, source trust, structured-response validation, asset handling, and user review.

Failure, retry, and recovery

AI provider calls can fail because of provider availability, model access, validation, output limits, timeouts, connection configuration, or ambiguous provider outcomes. Blackcap keeps those failures inside the AI job/usage model rather than applying partial output as if it were complete.

Where supported, a retry checks saved provider/request state before issuing another billable provider request. If the provider outcome is uncertain, Blackcap can enter a recovery state so a user is not encouraged to spend again merely because a response was slow. Quality Profile failure governance can also disable repeatedly failing profiles according to configured policy.

Privacy, retention, and review

Each AI surface explains that the relevant feature data is sent to the configured provider. That disclosure is separate from the AI Seed-spend confirmation.

Blackcap retains only the AI records and assets required by the feature, its configured retention policy, operational reconciliation, or review workflow. Temporary/generated assets are cleaned up through the normal retention system. Inventory Photo Analysis and Recipe Photo workflows do not need to retain arbitrary source media forever merely to prove that AI once ran; the feature-specific retention rules determine what evidence remains.

AI output should be treated as assisted output. Blackcap validates structured responses where possible, preserves deterministic source evidence, and uses review-before-apply behavior for workflows where an incorrect result would otherwise change durable recipe or inventory data.

Administration and troubleshooting

Configuration → Platform → AI manages provider connections, use cases, Quality Profiles, model/capability choices, AI Seed pricing, and related controls.
AI Usage provides authorized usage, outcome, cost, provider-ID, and reconciliation information.
Organizations / Users / Account expose the appropriate organization or personal AI Seed balances according to the viewer's permissions.
Data Cleanup handles retained AI assets according to their use-case retention rules.
AI Troubleshooting covers provider connections, model/profile configuration, Seed reservations, provider failures, validation failures, and retained assets.

More information

AI in Blackcap — detailed AI administration and subsystem behavior.
AI Providers and Connections — provider adapters, capabilities, credentials, model discovery, and Quality Profile configuration.
AI Seeds and Usage — balances, reservation/settlement, AI Usage, cost reporting, and retention.
AI Recipe Image Generation — Recipe and Meal image generation workflow.
Social Recipe Import — deterministic and optional AI-assisted social extraction.
Meal Planner — Plan Meals (what to eat), Plan Meal (how to coordinate one Meal), Suggestions, and saved coordinated Meal timelines.
Kitchen Inventory — inventory workflows that can use optional Inventory Photo Analysis.
Get Help and Support Requests — Support Chat and escalation.

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.

On this page