AI Settings

The AI Settings page is the central hub for managing the artificial intelligence capabilities of Freedam. It allows administrators to connect various AI providers, assign specific models to system tasks, and monitor the financial and technical performance of AI-driven features like chat enrichment and image studio operations.

This feature is designed for system administrators and financial controllers who need to ensure AI services are correctly configured, cost-effective, and performing within expected latency limits.

Page Overview

• Purpose: To manage the integration, routing, and auditing of AI services.
• When to use it: Use this page when setting up new AI capabilities, troubleshooting failed AI tasks, or reviewing monthly AI expenditures.
• What you can do here:
  • Map specific AI models to system operations (e.g., "Asset Tagging").
  • Monitor real-time token usage and costs.
  • Audit AI chat sessions and Studio image edits.
  • Verify the health and connectivity of AI providers.
  • Configure global AI system settings and API credentials.

Who can use it

• The AI Operations area is reserved for administrators who have been granted the "Administer AI Operations" permission.
• A separate "View AI costs" permission unlocks the cost dashboards (Costs & Pricing, Operations Log with cost columns, cost trends). Admins without this extra permission can still manage model bindings but will not see spend figures.
• The Chat Analytics tab is further gated by the "Administer chat system" permission.
• The Studio audit tab is only visible to administrators with the "View Studio audit" permission, and only when the AI Studio feature is included in your current plan.

Page Layout

• Top bar: Contains the page title "AI Operations" and a tab navigation menu to switch between different management views.
• Main area: Displays the content for the selected tab, such as usage charts, data tables for logs, or configuration forms for model mapping.
• Dialogs: Pop-up windows used for inspecting specific operation details, chat message histories, or high-resolution Studio renditions.

Main Features

Operation Mapping

• What it's for: Assigning a specific AI provider and model to a functional task in the app.
• Typical use: Selecting "GPT-4o" from "OpenAI" to handle the "Chat" operation.
• Result: The system will use the chosen model whenever that specific AI task is triggered by a user.
• Operations you can route: Freedam ships 17 mappable operations, grouped into four categories:
  • Vision: Focus Point Detection, Image Enrichment (combined OCR, tagging, captioning, and classification in a single call).
  • Embeddings: Generate Asset Embeddings, Search Phrase Embeddings (powering semantic search).
  • Image Generation: Image Crop, Remove Persons, Image Edit, Remove Background, Person Segmentation, Add Background, Image Upscale.
  • Text: Chat Query, Batch Naming, Collection Naming, Documentation Generation, Rules Explanation, Layout Constraint Generation.
• Every operation declares the inputs and outputs it needs (text, image, embeddings, background removal, segmentation, or upscaling), and the page automatically filters the model picker to models that support those capabilities.

Usage Analytics

• What it's for: Visualizing trends in costs, token consumption, and request volume.
• Typical use: Checking the "Cost & Activity Trends" chart to see if a recent feature launch caused a spike in spend.
• Result: Provides data-driven insights into how AI resources are being consumed over time.
• What's tracked: Every AI call records the provider, model, input and output token counts, total cost in US dollars, response time in milliseconds, success or failure, and any error message returned by the provider. Overview cards show all-time spend, today's spend, average cost per operation, average latency, and an overall error rate percentage.

Operations Log

• What it's for: A detailed, searchable history of every AI request made by the system.
• Typical use: Filtering by "Failed" status to identify why certain asset enrichments did not complete.
• Result: Displays the exact model used, the latency of the request, and any error messages returned.
• Retention: AI operation records are kept indefinitely by default, so you have a full audit trail for budget reconciliation and historical troubleshooting.

Provider & Model Registry

• What it's for: Checking the health and capabilities of connected AI services.
• Typical use: Verifying if a provider is "Healthy" and seeing which "Input" and "Output" types (like text or image) a model supports.
• Result: Ensures the system only attempts to use models that are currently accessible and capable of the task.

Detailed Feature Documentation

Operation Mapping

• Purpose: To define which AI engine powers specific app features.
• Where to find it: In the main area, click the Operation Mapping tab.
• What you'll see: A table listing every system operation, its required input/output types, and dropdowns to select a Provider and Model.

How to use it:

1. Locate the operation you wish to configure (e.g., "Asset Tagging").
2. Click the Select provider dropdown and choose an available service.
3. Click the Select model dropdown to choose a compatible model.
4. If the status badge shows "Invalid," check the error message below the dropdown for requirement mismatches.
5. Click Save bindings at the top right to apply changes.

Operations Log

• Purpose: To audit individual AI transactions for troubleshooting and cost verification.
• Where to find it: In the main area, click the Operations Log tab.
• What you'll see: A filterable list of requests including timestamps, token counts, costs, and success/failure badges.

How to use it:

1. Use the Operation, Provider, or Status dropdowns to narrow the list.
2. Click the Start date or End date buttons to select a specific timeframe from the calendar.
3. Review the Latency column to identify slow-performing models.
4. Click the Eye icon on any row to view the full technical details of that specific operation.

AI Settings (Configuration)

• Purpose: To manage API keys and global behavior toggles.
• Where to find it: In the main area, click the Settings tab.
• What you'll see: Grouped configuration cards (e.g., "AI Providers") containing text fields for keys and switches for feature toggles.

How to use it:

1. Locate the setting you need to change.
2. For API keys, type the new value into the Value: field (the input will be masked for security).
3. For feature toggles, click the Switch to change between Enabled and Disabled.
4. Click Save Changes in the top banner that appears once a modification is made.

Complete Workflows

Workflow: Updating an AI Model for Better Performance

• Goal: Switch a feature to a more powerful or cheaper model.
• Prerequisites: The new model must be registered in the Provider & Model Registry.

Steps:

1. Click the Operation Mapping tab.
2. Find the operation you want to update in the list.
3. Select the new Provider from the dropdown.
4. Select the desired Model from the second dropdown.
5. Verify that the Status badge turns green and says Valid.
6. Click Save bindings.

• Expected result: Future requests for that feature will immediately begin using the new model.

Workflow: Investigating AI Cost Spikes

• Goal: Identify which user or feature is consuming the most budget.
• Prerequisites: Permissions to view costs (admin.ai_costs).

Steps:

1. Click the Costs & Pricing tab.
2. Select a timeframe (e.g., "Last 30 Days") from the period selector dropdown.
3. Review the Costs by Operation pie chart to see which feature is most expensive.
4. Scroll to the Cost by Model table to see if a specific model has a high Avg Cost.
5. Switch to the Chat Analytics tab to see if specific users have high Total Cost in the User Stats table.

• Expected result: Identification of the specific model or user behavior driving costs.

What happens behind the scenes

• Smart routing: When a feature triggers an AI task, Freedam looks up the provider and model you assigned on the Operation Mapping tab and sends the request there. If a provider is marked unavailable (missing or invalid API key), the task fails fast rather than silently falling back.
• Cost recording: The moment a provider returns a response, Freedam records the operation — provider, model, input tokens, output tokens, total tokens, cost in USD, latency, and success flag — so it appears in the Operations Log and Cost analytics within seconds.
• Chat session lifecycle: Chat sessions track total messages, total tokens, and running cost per conversation. Old chat sessions are swept daily at 2:00 AM: anything with no activity for more than 30 days (or past its own expiry date) is archived and removed from the live list.
• Model compatibility guard: Saving a mapping with a "required input" (like image) against a text-only model is blocked before it can affect end-users.
• Secrets protection: Provider API keys entered on the Settings tab are stored as masked values and never echoed back in full.

Good to know

• Cost Analytics freshness: Overview stats, today's cost, cost trends, and breakdowns by operation type / provider / model are computed directly from stored operation records, so the figures are live — a newly completed task shows up on your next refresh.
• Chat dashboards: The chat overview shows total sessions, active sessions today, total messages, total tokens used, aggregate cost, and average messages per session. Daily usage and cost trend charts look back 30 days by default; user-level rollups are sorted by spend so the heaviest consumers surface at the top.
• Studio audit: The Studio sessions list shows the 100 most recent editing sessions across the workspace with a running total cost per session. Each rendition dialog traces back to the exact prompt, tool, token count, and user who produced it.

Tips and Best Practices

• Check Compatibility: When mapping models, the system automatically filters the list to show only models that support the required inputs (e.g., a model must support "Image" input for Studio operations).
• Monitor Latency: If users complain about slowness, check the Operations Log for high "ms" values. You may need to switch to a faster model in Operation Mapping.
• Resetting Changes: If you make a mistake while editing settings or mappings, click the Reset or Discard Changes button before saving to revert to the previous state.
• Cost gating: If a teammate cannot see cost columns but can still change mappings, they are missing the "View AI costs" permission — a useful way to let an engineer manage bindings without exposing spend.

Troubleshooting

Issue: Operation Mapping shows "Invalid" status

• Symptoms: The status badge is red, and the "Save bindings" button is disabled.
• Cause: The selected model does not support the required capabilities (e.g., it cannot output images) or the provider and model do not share a required capability.
• Fix: 1. Look at the error message below the model dropdown. 2. Select a different model that supports the "Required Input" and "Required Output" listed in that row.
• Prevention: Always check the "Required Capabilities" in the Operation Details dialog (Eye icon) before switching models.

Issue: Provider shows "Unavailable" status

• Symptoms: The status badge in the Providers tab is red.
• Cause: The API key is missing, incorrect, or the provider's service is currently down.
• Fix: 1. Go to the Settings tab. 2. Ensure the API key for that provider is correctly entered. 3. Check the provider's official status page.
• Prevention: Ensure API keys are updated before they expire.