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 and Gemini are implemented provider families, subject to configured credentials and registered capabilities.

Current use cases include social recipe enhancement/review and recipe image generation. AI output is reviewed and validated by the feature workflow; it does not replace deterministic source extraction or organization permissions.

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, Social Recipe Extraction, and Support Chat summaries. Support Chat also reports sessions, AI requests, successes/failures, resolved-without-support, escalations, provider failures, abandonment, average turns, average latency, AI Seeds used, and estimated provider cost. All summaries follow the current report filters.

Available row actions include:

🛟 View support chat for retained Support Chat history;
🖼️ View generated image while the generated candidate remains retained;
📋 Copy Provider Request ID for System Admin provider correlation when an identifier was captured.

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.

Two 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/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
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_connections
ai_use_cases
ai_profiles
ai_drupe_accounts
ai_organization_entitlements
ai_drupe_buckets
ai_jobs
ai_media_artifacts
ai_drupe_reservations
ai_drupe_ledger_entries
ai_generated_image_candidates
ai_usage_events
support_chat_sessions
support_chat_messages
support_chat_message_sources
ai_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.

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 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.08.09.19 keeps the deterministic provider-independent Recipe Image phase and extends deterministic Support Chat lifecycle coverage without calling OpenAI or Gemini. The Support Chat phase verifies untouched open/reopen suggestions, the first real message, multi-turn continuation, correlated AI Usage with zero Support Chat AI Seed charge, resolved-without-support terminal state, the 🛟 AI Usage transcript path, Extension user/organization isolation and continuation, terminal Extension transcript email routing, Support Case transcript bubble rendering, active-state cleanup after resolution/escalation, provider-failure fallback to human support, and transcript-purge behavior while usage survives.

System Admin tool regression verifies the expanded API Tester AI Usage entries and all 16 AI Database resources, including protected Support Chat metadata resources. Optional organization backup/restore now creates a Support Chat session with user/assistant messages and a documentation-source child row, purges it after the backup, and verifies the full session → messages → source relationship is restored.

The Recipe Image phase continues to validate reservation/settlement, configured profile cost, usage recording, generated-image review, and normal recipe acceptance/cache integration. Focused tests remain responsible for exhaustive filter combinations, model/provider availability contracts, UI-only details, SQLite/PostgreSQL query parity, organization/personal AI Seed accounting, pricing calculations, and social-recipe evidence isolation.

The deterministic regression providers never call OpenAI or Gemini.

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 and Gemini provider families, connections, use cases, profiles, 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.

On this page