🤖 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 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

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 report. It supports authorized organization selection, date range, provider, connection, use case, profile, user, result, funding source, sort, page, and records-per-page filters.

The page uses server-side filtering, counting, summary aggregation, stable ordering, and paging. Only the column header remains sticky while the rest of the page scrolls normally. A contextual horizontal scrollbar is synchronized with the table: the native scrollbar is used when visible; otherwise the anchored proxy is active. Paging controls remain anchored at the bottom of the viewport while the report table is active.

Provider request identifiers and provider-reported input/output/image token counts are visible only to System Admins. AI Seed charges remain separate from provider token counts.

JSON API

GET /api/admin/ai/usage returns the same authorized report as safe JSON. It includes:

• selected scope and authorized organization IDs;
• normalized filters;
• full-filter summary and server-paged rows;
• record range and supported page sizes;
• safe organization, user, connection, use-case, and profile option lists.

The reporting service removes provider request IDs, provider token counts, provider usage payloads, and provider response metadata for non-System Admins before the API response is built. Provider credentials and raw prompts are never returned.

Reconciliation export

GET /admin/ai/usage/reconciliation.csv is System Admin-only. It uses the same authorized filters as the report and includes provider billing fields, safe request identifiers, normalized provider token counts, retry lineage, and AI Seed accounting values.

API Tester

The AI Usage category exposes:

• AI Usage Report
• Download AI Provider Billing Reconciliation CSV
• Organization AI Seed Balance
• Organization AI Seed Recent Adjustments
• Personal AI Seed Balance

The registry remains curated. Read operations are executable through the authenticated tester. Reconciliation remains System Admin-only. Adjustment writes are intentionally not added as automatically safe API Tester operations because they alter audited balances.

Database Admin

Database Admin exposes all AI foundation tables in a System Admin-only AI group:

1. ai_provider_connections
2. ai_use_cases
3. ai_profiles
4. ai_drupe_accounts
5. ai_organization_entitlements
6. ai_drupe_buckets
7. ai_jobs
8. ai_drupe_reservations
9. ai_drupe_ledger_entries
10. ai_generated_image_candidates
11. ai_usage_events
12. ai_recipe_image_state

The resources use explicit safe display/search/filter columns. Encrypted provider credentials, raw prompts, provider snapshots, internal file paths, provenance payloads, allocation JSON, and other private JSON fields are hidden. Purpose-built AI pages remain the supported place for normal changes; Database Admin is for inspection and narrowly controlled troubleshooting.

Permissions summary

Regression coverage

Regression suite 2026.07.30.4 retains deterministic provider-independent recipe image generation and adds checks for:

• organization-scoped AI Usage JSON reporting;
• omission of provider request/token diagnostics for Org Admins;
• dedicated AI Usage page rendering;
• System Admin all-organization AI Usage API access;
• API Tester AI Usage endpoint exposure;
• all 13 AI Database Admin resources;
• protected AI JSON/private columns remaining hidden;
• existing reservation, one-time settlement, usage recording, candidate review, and normal image acceptance/cache integration;
• custom administrator-configured recipe-image profile names and prices without assuming the original Medium/High seed configuration.

The deterministic phase selects an enabled configured profile and uses its authoritative current AI Seed cost for balance preparation, reservation, settlement, and balance verification. Original migration seed values remain covered by migration/unit tests rather than mutable runtime regression state.

Focused tests additionally cover organization balance facets, on-demand adjustment history, global personal balance privacy, System Admin organization-vs-personal unlimited behavior, provider diagnostic capture, SQLite/PostgreSQL-safe queries, immediate anchor changes without duplicate grants, overlap rollback, and consistent AI Seed spelling and purple allotment fill.

The deterministic regression provider never calls 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.