๐ค AI Providers and Connections
Audience: System Admin, Org Admin, Deployment Administrator, Developer Related: Overview ยท Seeds And Usage ยท Environment And Secrets
AI provider adapters expose declared capabilities through a shared registry and base interface. Provider connections store the configuration required to invoke a provider without coupling feature code directly to OpenAI, Gemini, or Anthropic Claude.
Administration pages show provider availability, connection state, supported use cases, test actions, and configuration scope. Secrets remain protected and must not be included in documentation or diagnostics.
Provider administration
Access
Only System Admins can open Configuration โ Platform โ AI. Org Admins may view their organization's finite balance and usage, but cannot change provider credentials, quality prices, monthly entitlements, or personal balances belonging to other users.
Provider connections
Blackcap supports multiple named OpenAI, Gemini, and Anthropic Claude connections at the same time, such as Production and Testing. A connection stores:
- provider type and friendly name;
- enabled state;
- encrypted credential status;
- safe test status and timestamps;
- safe failure category.
Provider connections no longer have a provider-level Default Model. Each quality profile selects the model for its own use case, so there is only one authoritative model choice for a generation request. Changing a connection or model on a quality profile preserves the other compatible profile settingsโsuch as token limits, Support Chat turn/history/retrieval limits, timeout, and social-media limitsโrather than resetting the profile to defaults. Only a setting that is genuinely incompatible with the newly selected model is disabled or normalized.
Provider and profile model fields use Blackcap's curated capability catalog. Selecting a provider connection limits the model, resolution, aspect-ratio, provider-quality, and output-format controls to combinations supported by that Blackcap adapter. The catalog intentionally describes what Blackcap knows how to do with each model rather than assuming that every model returned by a vendor model-list API supports every Blackcap use case.
For saved provider connections, Configuration โ Platform โ AI provides an explicit Refresh Available Models action. Refresh opens an in-page progress/result dialog and calls the provider's model-list API without reloading AI Configuration. Blackcap records only a curated relevant subset of the provider inventory rather than retaining every embedding, realtime, audio, moderation, fine-tune, or other specialized model returned by a broad vendor listing. The result dialog shows the provider's total reported count, the Blackcap-relevant count, how many unrelated/specialized models were ignored, newly usable models, relevant provider-only models, and previously tracked models that are no longer reported. It does not edit, migrate, or substitute any Quality Profile. A tracked model that disappears remains in history as Unavailable rather than being deleted, so existing Quality Profiles and historical AI Usage remain understandable.
The main provider table stays intentionally compact. Relevant provider-only models are reviewed inside Edit Provider, where they are shown as compact tiles. A System Admin can promote a discovered provider-only model without a Blackcap code release by mapping it to an existing Blackcap-supported capability template from the same provider. The promoted model then becomes selectable for the same AI use cases and profile controls as that template, while all existing Quality Profiles remain unchanged. This is appropriate only when the new provider model is API/capability-compatible with the selected template; genuinely new provider behavior still requires a Blackcap capability implementation rather than an unsafe alias.
Each refresh also records the provider connection's last updated timestamp and refreshes pricing from the provider's official public pricing documentation for OpenAI, Anthropic Claude, and Google Gemini. Provider model-list APIs do not include price sheets, so Blackcap reads the official standard paid API pricing page, retains previously verified connection pricing if that page is temporarily unavailable or only partially parseable, and uses the bundled versioned pricing snapshot only as a fallback. Pricing updated changes only when the persisted material rates actually change; a successful check with unchanged prices leaves that timestamp alone. Blackcap never infers a price from a similarly named model when the provider has not published a matching rate.
Blackcap keeps provider discovery separate from Blackcap capability support. A relevant model returned by OpenAI, Gemini, or Anthropic can therefore appear as Provider only when Blackcap has not yet declared the API surface, structured-output behavior, image options, reasoning options, or use cases it safely supports. Refreshing provider inventory alone never guesses those capabilities. Models become selectable when they are both reported by the provider and present in Blackcap's curated capability catalog. The catalog currently includes Blackcap support for the OpenAI GPT-5.6 Luna/Terra/Sol text/vision family and GPT Image 2.5 Flare/Sunburst image-generation models in addition to the previously supported models. The connection also records and displays the installed provider SDK distribution/version separately from the discovered model catalog, so a System Admin can distinguish "the provider reports this model" from "this Blackcap runtime has the SDK/capability support needed to use it."
The provider Test action also refreshes the stored model inventory and, for inexpensive text surfaces, performs the existing endpoint-specific capability probes. Manual Refresh Available Models is intentionally cheaper: it refreshes the model-list inventory without issuing billable generation probes. Recipe image generation and transcription do not generate billable test media merely to populate Configuration. If provider discovery is temporarily unavailable, Blackcap preserves the last stored catalog and all existing Quality Profiles rather than silently changing configuration. New connections cannot be refreshed until their credential has first been saved.
The availability checks apply across recipe image generation, social recipe extraction, Recipe Photo, Inventory Photo Analysis, Plan Meal, Plan Meals, Support Chat, Create/Modify SQL Query, and specialized transcription where applicable. Existing profiles whose selected model is no longer reported remain visible with an Unavailable warning so the configuration can be repaired explicitly. Provider details show the persisted relevant provider inventory together with New + usable, Provider only, and Unavailable states; the main Quality Profile configuration continues to use Blackcap's supported capability catalog.
OpenAI recovery-enabled image generation supports gpt-image-2, gpt-image-2.5-flare, and gpt-image-2.5-sunburst. Gemini supports gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-3-pro-image, and legacy gemini-2.5-flash-image. Anthropic Claude uses the Messages API for structured text/vision requests; Blackcap's curated Claude catalog includes Haiku 4.5, Sonnet 5, Opus 5, and Fable 5.1 for the compatible text/vision use cases. Claude does not provide a Blackcap image-generation adapter and is not offered for direct social-video review. Gemini generation prefers stored/background Interactions API requests where the selected model supports background execution. Blackcap persists the returned interaction ID before waiting for completion, so a recovered job can call interactions.get instead of submitting a second paid request. Background execution is model-specific: if Gemini definitively rejects background=true before starting an operation, Blackcap retries that same stored Interaction synchronously, consumes the returned response directly, and does not poll the synchronous result with interactions.get. The Gemini API does not accept Enterprise Agent Platform labels; Blackcap retains instance, organization, user, and job attribution in its own usage records instead. The Python Interactions path preserves Blackcap's structured-output, multimodal, reasoning-profile, and Google Search options that are supported by Interactions; Blackcap does not currently configure Gemini custom safety settings, which the Interactions API does not support. Support Chat is an intentional exception to the background preference: its short Gemini responses use a synchronous stored Interaction so they can be checkpointed directly without a follow-up interactions.get retrieval dependency. The image path requests JPEG output and never retries the same request merely to remove unsupported fields.
A saved API key is never returned to the browser. Enter a new key only to create or rotate a credential. Connection tests do not consume AI Seeds. They make a minimal provider API request that may still be recorded or billed under the provider account.
Use case and quality profiles
Blackcap currently implements eight major AI use cases: ๐ผ๏ธ Recipe / Meal Image Generation, ๐ฌ Social Recipe Extraction, ๐ท Recipe Photo Extraction, ๐ฆ Inventory Photo Analysis, ๐ฝ๏ธ Plan Meal / Letโs Cook Meal Plan, ๐๏ธ Plan Meals, ๐ Support Chat, and โจ Create / Modify SQL Query. Social Recipe Extraction may also use a specialized ๐๏ธ Transcription model where the provider workflow separates audio transcription from recipe extraction. User-configurable AI use cases use the normal quality-profile/provider-selection model, while internal sub-interactions such as Plan Meals Find & Add remain correlated to their parent durable job and interaction records.
Each user-visible profile is provider-independent and contains:
- display name and description;
- enabled/default status, automatic disable reason, consecutive-failure state, and display order;
- configurable AI Seed cost;
- assigned provider connection and model;
- provider-supported resolution, aspect ratio, quality control, and output format;
- a small allowlisted provider-options object.
Changing a profile affects new jobs only. Every submitted job snapshots the approved price, provider connection, model, output settings, and prompt version. Disabling a connection before a queued job executes causes a safe failure and reservation release; Blackcap does not silently send content to a fallback provider.
To limit repeated provider cost from a broken Quality Profile, Blackcap tracks consecutive terminal AI Usage results for each profile. A success resets the live profile's streak. Two consecutive failures automatically disable the profile and set Disable Reason to Failed twice; if it was the default, the next enabled profile becomes the default. A System Admin can inspect the failure text from the profile's ๐ AI Usage action, correct the profile/provider, and explicitly re-enable it. Manual enable/disable clears the automatic reason and resets the streak.
Each Provider Connection also has a ๐ provider platform action. It opens the provider's own console in a new browser tab so a System Admin can review provider-side usage and billing without remembering the destination: OpenAI opens the OpenAI Platform home, Gemini opens Google AI Studio Usage, and Anthropic Claude opens Claude Platform Usage.
Monthly organization allotments
A System Admin configures the recurring amount, anchor day, billing timezone, enabled state, and effective behavior.
- Beginning next billing period preserves the current period and applies the new entitlement at the next non-overlapping boundary.
- Adjust the current period now atomically updates the existing current monthly bucketโs boundaries and configured amount. Spent and reserved amounts are preserved, the operation cannot reduce the bucket below those commitments, and Blackcap does not create a second overlapping monthly grant. If an overlapping bucket already exists, the transaction is rejected and rolled back for review.
Anchor days 29, 30, and 31 clamp to the final valid day of a short month without permanently drifting. Period boundaries are calculated in the billing timezone, persisted in UTC, and treated as start-inclusive/end-exclusive. Scheduled maintenance and lazy balance reads both create a missing current-period grant idempotently.
Manual adjustments
System Admins may grant or correct organization and personal balances. A reason is mandatory. Adjustments create append-only ledger entries; the application never performs an unexplained mutable balance edit. Ordinary corrections cannot make available AI Seeds negative.
Usage reporting
The dedicated Administration โ AI Usage page filters by date range, provider, connection, use case, profile, organization, user, outcome, source, andโwhen System Admin cost data is availableโestimated provider-cost range. Provider, connection, and profile are linked facets: selecting any one narrows the compatible values in the other two. Selecting an organization narrows the user list to users associated with that organization, while generated regression-test and diagnostic-clone identities are excluded from the normal user selector.
The report tracks the quality-profile name, configured AI Seed usage, provider/model, outcome, a user-friendly failure reason when a request fails, normalized provider token usage, latency, and estimated provider cost. Configured AI Seed usage is recorded even for Unlimited accounts; Unlimited determines whether a finite balance is debited, not whether the product usage occurred. Provider-owned correlation identifiers, estimated provider cost, and detailed provider-token diagnostics are visible only to System Admins. The AI Usage Provider ID column prefers the provider's HTTP request ID; when a provider surface only retains a durable response/message identifier, Blackcap shows that instead and labels it as a response ID in the tooltip. This is particularly important for streamed Anthropic Messages, where the HTTP request ID is captured from the stream wrapper while the final Claude Message supplies its msg_... response ID. The report includes total estimated provider cost plus summaries for Recipe Image Generation, Social Recipe Extraction, and Support Chat, all using the current report filters.
AI Seed charges come from the profile snapshot, not from provider token usage. This preserves historical product pricing even when Blackcap changes providers, models, or provider costs.
AI Data Retention
This use-case setting controls how long Blackcap keeps generated image candidates that were not selected for a recipe. The purge job removes those unused or rejected candidate files after the configured number of days. Images accepted and saved with a recipe are moved into the normal recipe image/cache workflow and are not deleted by this setting.
Administration locations after the AI administration reorganization
Configuration โ Platform โ AI now contains only platform configuration: billing identity, provider connections, use cases, quality profiles, models, prices, and retention. Organization and personal balance editors are no longer duplicated on this page.
Use:
- Administration โ Organizations for organization AI Seed summaries and System Admin adjustments;
- Administration โ Users for global personal AI Seed summaries and System Admin adjustments;
- Administration โ AI Usage for authorized organization-scoped reporting and Provider Billing Reconciliation export;
- Administration โ Data Cleanup for asset-type-aware unused AI asset cleanup.
The Add Provider dialog has a static backdrop and explicit Cancel action, so an accidental click outside the dialog does not discard entered credentials or settings.
AI Data Retention is configured per use case and applies to terminal AI jobs, AI Usage/accounting history, and use-case evidence; Support Chat transcript history uses the same value. Unused generated assets also use that value unless the separate Purge configuration enables the global unused-asset retention override. Accepted durable recipe images are unaffected.
Administration APIs, Database resources, and tests
The authenticated JSON report is available at GET /api/admin/ai/usage and is exposed in the curated API Tester together with the System Admin reconciliation CSV and read-only organization/personal balance endpoints. Non-System Admin report models remove provider request IDs, provider token counts, provider usage payloads, and provider response metadata before serialization.
Database Admin exposes the AI foundation tables plus metadata-oriented Support Chat Sessions, Support Chat Messages, and Support Chat Message Sources resources to System Admins. AI Usage exposes cached/reasoning token counts, Support Chat correlation IDs, prompt/documentation versions, and estimated provider cost where available. Credentials, raw prompts, Support Chat message text/context payloads, provider snapshots, file paths, provenance, and private JSON payloads remain hidden.
The deterministic regression suite verifies AI Usage authorization/privacy, filters and summaries, API Tester coverage, AI Database resources, Support Chat lifecycle/usage behavior, backup/restore of Support Chat session โ message โ source relationships, and the mocked recipe-image/accounting workflow without calling paid providers. The recipe-image phase uses a currently enabled configured profile and its authoritative AI Seed cost; it does not require the original seeded profile names or prices. See AI Administration, AI Seeds, and Usage Reporting.
Provider adapter architecture
Boundary
Feature routes and templates call provider-independent AI services. They never construct OpenAI, Gemini, or Anthropic Claude requests. Provider-specific behavior belongs in an adapter registered by ai_provider_registry.py.
The current adapter contract supports:
- validating a configured connection and discovering available models;
- translating normalized text, structured-output, image-input, or image-generation requests as supported by the provider;
- returning validated image bytes/MIME type for image-generation providers or normalized structured text results for text/vision providers;
- returning model, safe request ID, and latency;
- normalizing input, output, image, and provider-specific usage;
- classifying authentication, rate limit, safety, timeout, unsupported setting, unavailable, invalid response, and permanent provider failures.
Current provider transport choices
- OpenAI image generation defaults to the configurable
gpt-image-2model. - Gemini image and compatible text/vision generation use the Gemini Interactions API with
store=True. Blackcap prefersbackground=Truewhen the selected model supports it, persists the interaction ID, and retrieves that same operation after restart instead of resubmitting it. If a model rejects background execution before submission, Blackcap falls back to a synchronous stored Interaction and checkpoints its returned response directly;gemini-3.6-flashis currently treated as a known background-unsupported model and goes directly to that synchronous path rather than making a doomed background attempt. Once any Gemini Interaction has been accepted and assigned an interaction ID, a later retrieval failure is never treated as schema incompatibility and never triggers a second provider submission. An interruption while a synchronous call is in flight is handled conservatively rather than automatically resubmitted. Current Interactions supports the structured-output and Google Search patterns Blackcap uses, but not custom safety settings; Blackcap does not currently configure provider-specific Gemini custom safety settings. - Anthropic Claude structured requests use the Messages API with
output_config.formatJSON Schema. Blackcap normalizes standard nullable type arrays such astype: ["number", "null"]into equivalentanyOfbranches before the Anthropic SDK schema transformer runs, avoiding an SDK-helper assertion while preserving the schema semantics. Compatible Claude 5 models expose configurable effort levels; thinking/reasoning tokens are part of the provider's inclusive billed output-token total and are recorded separately only as an observability breakdown. - Blackcap pins the OpenAI, Google GenAI, and Anthropic Python SDKs in both source/cloud requirements. Anthropic Claude support uses
anthropic==1.3.0; compiled builds explicitly include and smoke-check its Models and Messages surfaces alongside the OpenAI/Gemini SDK checks. Blackcap does not retry an uncertain Gemini Interactions request throughgenerateContent, because doing so could create and charge for a duplicate image.
Adding a provider
- Implement
AIProviderAdapterin a dedicated module. - Lazy-import the provider SDK so installations that do not configure that provider can still start.
- Translate only allowlisted options. Never pass arbitrary UI JSON directly to an SDK.
- Return
AIImageResult; never attach images or alter AI Seed balances inside the adapter. - Raise
AIProviderErrorwith a normalized category and a user-safe message. - Do not log credentials, complete raw responses, or full prompts.
- Register the adapter and add mocked success/failure/secret-redaction tests.
- Add a paid live test only behind
BLACKCAP_RUN_LIVE_AI_TESTS=1and explicit provider model variables.
Job and accounting flow
route
-> AI image service
-> resolve use case/profile/connection
-> snapshot configuration and price
-> reserve selected AI Seed account transactionally
-> durable job
-> provider adapter
-> validate and save candidate
-> settle reservation exactly once
-> usage event exactly once
-> explicit user acceptance
-> existing recipe image and cache services
If a provider fails before a usable image exists, the reservation is released. If a usable validated candidate exists but a later database or cache step fails, the candidate is preserved and the job enters recovery rather than releasing the reservation. Restart reconciliation settles and records that result once without issuing a second provider request.
Database rules
All SQL lives in inky_admin/repositories/ai_repository.py and uses the centralized application database service. Domain services, adapters, workers, routes, and templates contain no direct SQL. Every query uses explicit columns. PostgreSQL row locking and SQLite controlled write transactions remain behind the database service boundary.
Financial ledger and usage rows intentionally do not depend on purgeable job or reservation foreign keys. Candidate files and operational jobs may have different retention policies without destroying accounting history.