🤖 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 or Gemini.

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 and Gemini connections at the same time, such as Production and Testing. A connection stores:

• provider type and friendly name;
• enabled state;
• encrypted credential status;
• optional default-model suggestion;
• safe test status and timestamps;
• safe failure category.

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 lists supported combinations rather than every model returned by a vendor model-list API, because model-list responses do not describe all image-output constraints.

OpenAI recovery-enabled generation currently uses gpt-image-2. Gemini supports gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-3-pro-image, and legacy gemini-2.5-flash-image. Gemini generation uses stateless Interactions API requests. 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 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

The only enabled use case is manual_recipe_image_generation. Future registry entries are seeded disabled and have no implementation path yet.

Each user-visible profile is provider-independent and contains:

• display name and description;
• enabled/default status 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.

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, and source. It reports requests, successes, failures, AI Seeds charged/released, safety rejections, average latency, and organization/user context. Safe provider request identifiers and normalized provider token fields are visible only to System Admins.

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.

Unused AI Asset 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.

Unused AI Asset Retention help is generated from the selected use case’s asset metadata. Manual recipe image generation refers to unselected generated recipe images; unknown use cases use neutral AI-asset wording.

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 all 12 AI foundation tables under a System Admin-only AI group. Credentials, raw prompts, provider snapshots, file paths, provenance, and private JSON payloads remain hidden.

Regression suite 2026.07.30.4 verifies organization-scoped usage reporting, non-System Admin provider-diagnostic privacy, System Admin report access, API Tester entries, all AI Database resources, and the deterministic recipe-image/accounting workflow. 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

Recipe routes and templates call the provider-independent AI image service. They never construct OpenAI or Gemini requests. Provider-specific behavior belongs in an adapter registered by ai_provider_registry.py.

The current adapter contract supports:

• validating a configured connection;
• translating a normalized image request;
• returning validated image bytes and MIME type;
• 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-2 model.
• Gemini image generation defaults to the configurable gemini-3.1-flash-image model and uses the Gemini Interactions API. Requests set store=False so Blackcap does not opt into provider-side interaction retention.
• Blackcap requires openai>=2.46.0 and google-genai>=2.13.0 so an ordinary requirements update advances existing environments to the current SDK lines used by these adapters. Blackcap does not retry an uncertain Gemini Interactions request through generateContent, because doing so could create and charge for a duplicate image.

Adding a provider

1. Implement AIProviderAdapter in a dedicated module.
2. Lazy-import the provider SDK so installations that do not configure that provider can still start.
3. Translate only allowlisted options. Never pass arbitrary UI JSON directly to an SDK.
4. Return AIImageResult; never attach images or alter AI Seed balances inside the adapter.
5. Raise AIProviderError with a normalized category and a user-safe message.
6. Do not log credentials, complete raw responses, or full prompts.
7. Register the adapter and add mocked success/failure/secret-redaction tests.
8. Add a paid live test only behind BLACKCAP_RUN_LIVE_AI_TESTS=1 and 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.