From 24a8fba7ff10fc5100b961da1138691f4b63f412 Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Wed, 20 May 2026 13:50:59 +0300 Subject: [PATCH 1/8] docs(config): update budget configuration and llm proxy documentation --- .../platform-managed-mode-configuration.md | 72 ++------------- .../codemie/api-configuration.md | 11 ++- .../litellm-proxy/budget-configuration.md | 38 ++++---- docs/admin/update/release-notes.md | 10 +-- .../project-user-management/index.mdx | 9 -- .../project-user-management/projects.md | 7 -- .../project-user-management/users.md | 7 -- .../workflows/configuration/examples.md | 89 ------------------- .../workflows/workflow-templates.md | 2 +- ...many-projects-a-user-can-be-assigned-to.md | 22 ----- ...-project-and-user-management-in-codemie.md | 33 ------- 11 files changed, 40 insertions(+), 260 deletions(-) delete mode 100644 faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md delete mode 100644 faq/how-do-i-enable-project-and-user-management-in-codemie.md diff --git a/docs/admin/configuration/access-control/platform-managed-mode-configuration.md b/docs/admin/configuration/access-control/platform-managed-mode-configuration.md index 50d697b3..428ce114 100644 --- a/docs/admin/configuration/access-control/platform-managed-mode-configuration.md +++ b/docs/admin/configuration/access-control/platform-managed-mode-configuration.md @@ -2,7 +2,7 @@ id: platform-managed-mode-configuration sidebar_position: 3 title: Platform-managed Mode Configuration -description: How to enable Platform-managed mode for fresh installations and when switching from Keycloak-managed mode +description: How to switch to Platform-managed mode and migrate existing Keycloak users pagination_prev: admin/configuration/access-control/access-control-overview pagination_next: null --- @@ -15,13 +15,6 @@ mode, where roles and project access are read from JWT claims on every request. For a comparison of both modes, see the [Access Control Overview](./index.md#deployment-modes). -## Deployment Scenarios - -| Scenario | Steps required | -| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| **Fresh installation** — deploying AI/Run CodeMie for the first time | [Step 1](#step-1-configure-helm-values) only | -| **Switching from Keycloak-managed mode** — existing deployment with users in Keycloak | [Step 1](#step-1-configure-helm-values) and [Step 2](#step-2-migrate-existing-keycloak-users-existing-deployments-only) | - ## Prerequisites - Access to the Kubernetes cluster and Helm values file of AI/Run CodeMie Backend and UI @@ -29,7 +22,7 @@ For a comparison of both modes, see the --- -## Step 1: Configure Helm Values +## Step 1: Enable Platform-managed Mode :::warning Both components must be updated The AI/Run CodeMie backend and the UI must be configured consistently. Enabling only one of them results @@ -38,24 +31,17 @@ in either missing UI controls or API errors. ### AI/Run CodeMie Backend -In the `codemie-api` Helm chart, add the following variables to the `extraEnv` list: +Set the `ENABLE_USER_MANAGEMENT` environment variable to `true` in the AI/Run CodeMie Backend +deployment. + +In the `codemie-api` Helm chart , add `ENABLE_USER_MANAGEMENT` to the `extraEnv` list: ```yaml extraEnv: - name: ENABLE_USER_MANAGEMENT value: 'true' - - name: USER_PROJECT_LIMIT - value: '3' ``` -`ENABLE_USER_MANAGEMENT` activates Platform-managed mode. When set to `true`, user roles -and project assignments are stored in the platform database and managed through the in-app -UI instead of being read from Keycloak JWT claims. - -`USER_PROJECT_LIMIT` sets the maximum number of shared projects a regular user can be -assigned to. Super Admins are always exempt from this limit. Adjust the value to match -your organisation's policy. - Apply the changes to the deployment. ### AI/Run CodeMie UI @@ -67,16 +53,8 @@ In the `codemie-ui` Helm chart `values.yaml`, set: ```yaml viteEnableUserManagement: true -viteEnableBudgetManagement: true ``` -`viteEnableUserManagement` tells the UI that Platform-managed mode is active. When set to -`true`, the **Users management** and **Projects management** tabs appear under -**Settings → Administration**. - -`viteEnableBudgetManagement` enables budget columns and the budget management section on -project detail pages. Set it to `false` if your deployment does not use budget tracking. - Apply the changes to the deployment. --- @@ -216,44 +194,6 @@ UPDATE users SET is_maintainer = true, is_admin = true WHERE email = ' -f values.yaml -n codemie - helm upgrade codemie-ui -f values.yaml -n codemie - ``` - -3. The `codemie-api` pod runs Alembic database migrations automatically on startup — no - manual database steps are required. The startup probe allows up to **600 seconds** for - migrations to complete. - - :::info Multiple replicas - If you run multiple `codemie-api` replicas, the migration runner acquires an exclusive - lock on the `alembic_version` table. Only the first replica to acquire the lock runs - the migration; the others wait and proceed once the lock is released. - ::: - -4. Verify the upgrade: log in as an admin and confirm the **Projects management** and - **Users management** tabs appear under **Settings → Administration**. - ---- - ## See Also - [API Configuration Reference — User Management Mode](../codemie/api-configuration.md#user-management-mode) diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index 69d02736..d79b3217 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -554,12 +554,11 @@ Configure LiteLLM proxy for unified LLM access, budget management, and usage tra ### Proxy Mode -| Parameter | Type | Default | Description | -| ------------------------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `LLM_PROXY_MODE` | string | `"internal"` | Proxy mode: `internal` (built-in routing), `lite_llm` (external LiteLLM proxy) | -| `LLM_PROXY_ENABLED` | boolean | `false` | Enable LLM proxy for centralized model access control | -| `LLM_PROXY_TIMEOUT` | integer | `300` | Max seconds to wait for proxy responses | -| `LLM_PROXY_EMBEDDINGS_DISABLED` | boolean | `false` | When `true`, bypasses the LiteLLM proxy for embedding requests and sends them directly to the native provider (e.g., Azure OpenAI). Useful when LiteLLM does not support a required embedding model or when lower-latency direct access is preferred for vector operations. Has no effect when `LLM_PROXY_ENABLED=false` or `LLM_PROXY_MODE=internal`. | +| Parameter | Type | Default | Description | +| ------------------- | ------- | ------------ | ------------------------------------------------------------------------------ | +| `LLM_PROXY_MODE` | string | `"internal"` | Proxy mode: `internal` (built-in routing), `lite_llm` (external LiteLLM proxy) | +| `LLM_PROXY_ENABLED` | boolean | `false` | Enable LLM proxy for centralized model access control | +| `LLM_PROXY_TIMEOUT` | integer | `300` | Max seconds to wait for proxy responses | ### LiteLLM Connection diff --git a/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md b/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md index 347d7942..59c7051a 100644 --- a/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md +++ b/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md @@ -93,27 +93,35 @@ The `budget_category` field controls which type of usage the budget applies to: Budget enforcement is disabled by default. To activate it, set the following environment variables in the CodeMie API deployment: -| Variable | Type | Default | Description | -| ----------------------------------- | ------- | ------- | -------------------------------------------------------------------------------- | -| `LLM_PROXY_BUDGET_CHECK_ENABLED` | boolean | `false` | Enables budget limit checking for LLM proxy requests | -| `LLM_PROXY_BUDGET_SYNC_ENABLED` | boolean | `false` | Syncs predefined budgets from `budgets-config.yaml` into the database on startup | -| `LLM_PROXY_BUDGET_BACKFILL_ENABLED` | boolean | `false` | Backfills user budget assignments from LiteLLM on startup for existing users | +| Variable | Type | Default | Description | +| ----------------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `LLM_PROXY_BUDGET_CHECK_ENABLED` | boolean | `false` | Enables LLM budget enforcement. When `true`, CodeMie actively enforces spending limits - LLM requests from users or projects that have exceeded their budget are blocked. Also enables budget API routes and background budget maintenance. | +| `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED` | boolean | `false` | Runs a post-startup reconciliation job that syncs predefined budgets from `budgets-config.yaml`, backfills user and project budget assignments, and aligns spending state with LiteLLM. Required for YAML budget definitions to take effect. | -**In Helm Values** (`values.yaml`): +### How budget enforcement works + +When `LLM_PROXY_BUDGET_CHECK_ENABLED` is enabled, CodeMie registers the budget enforcement provider and enables budget API routes. LLM requests are checked against active budgets - requests from users or projects that have exceeded their `max_budget` are rejected; requests approaching `soft_budget` generate warnings. + +**Predefined budgets from `budgets-config.yaml` are not loaded by `LLM_PROXY_BUDGET_CHECK_ENABLED` alone.** To sync the YAML config into the database and LiteLLM, you must also set `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED=true`. The reconciliation job runs once after startup and: + +1. Syncs predefined budgets from `budgets-config.yaml` into PostgreSQL and LiteLLM - config is the **source of truth**: existing budgets are created or updated, spending counters are preserved unless `budget_duration` changes +2. Syncs current spending state from LiteLLM back into CodeMie +3. Backfills budget assignments for existing users and projects + +Without `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED=true`, changes to `budgets-config.yaml` never reach the database even after a pod restart. + +**In AI/Run CodeMie Backend values** (`values.yaml`): ```yaml -api: - env: - - name: LLM_PROXY_BUDGET_CHECK_ENABLED - value: "true" - - name: LLM_PROXY_BUDGET_SYNC_ENABLED - value: "true" - - name: LLM_PROXY_BUDGET_BACKFILL_ENABLED - value: "true" +extraEnv: + - name: LLM_PROXY_BUDGET_CHECK_ENABLED + value: "true" + - name: LLM_PROXY_BUDGET_RECONCILIATION_ENABLED + value: "true" ``` :::warning -`LLM_PROXY_BUDGET_SYNC_ENABLED` must be `true` for predefined budgets from `budgets-config.yaml` to be loaded into the database. Without it, budget definitions in the config file have no effect. +`LLM_PROXY_BUDGET_RECONCILIATION_ENABLED` must be `true` for predefined budgets from `budgets-config.yaml` to be loaded into the database and LiteLLM. Without it, budget definitions in the config file have no effect even after a pod restart. ::: ## Customizing Budgets via Helm diff --git a/docs/admin/update/release-notes.md b/docs/admin/update/release-notes.md index 2d8b8ab1..59a11709 100644 --- a/docs/admin/update/release-notes.md +++ b/docs/admin/update/release-notes.md @@ -319,11 +319,11 @@ No third-party component updates in this release. Three new environment variables have been introduced to control LLM budget enforcement. All default to `false` (disabled): -| Variable | Default | Description | -| ----------------------------------- | ------- | -------------------------------------------------------------------------------- | -| `LLM_PROXY_BUDGET_CHECK_ENABLED` | `false` | Enables budget limit checking for LLM proxy requests | -| `LLM_PROXY_BUDGET_SYNC_ENABLED` | `false` | Syncs predefined budgets from `budgets-config.yaml` into the database on startup | -| `LLM_PROXY_BUDGET_BACKFILL_ENABLED` | `false` | Backfills user budget assignments from LiteLLM on startup for existing users | +| Variable | Default | Description | +| ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `LLM_PROXY_BUDGET_CHECK_ENABLED` | `false` | Enables LLM budget enforcement. When `true`, requests that exceed configured spending limits are blocked. | +| `LLM_PROXY_BUDGET_SYNC_ENABLED` | `false` | Syncs predefined budgets from `budgets-config.yaml` into the database on startup | +| `LLM_PROXY_BUDGET_BACKFILL_ENABLED` | `false` | Backfills user budget assignments from LiteLLM on startup for existing users | See [Budget Configuration](../configuration/extensions/litellm-proxy/budget-configuration.md) and [API Configuration](../configuration/codemie/api-configuration.md) for details. diff --git a/docs/user-guide/project-user-management/index.mdx b/docs/user-guide/project-user-management/index.mdx index 79301541..9666ba67 100644 --- a/docs/user-guide/project-user-management/index.mdx +++ b/docs/user-guide/project-user-management/index.mdx @@ -19,15 +19,6 @@ users and their project memberships across the entire platform. The **Project & User Management** section is accessible via the **Profile** icon in the bottom-left corner → **Settings → Administration**. -:::info Admin configuration required -Project & User Management requires **Platform-managed mode** to be enabled by a platform -administrator. If you do not see the **Projects management** or **Users management** tabs -under **Settings → Administration**, contact your administrator. - -See [Platform-managed Mode Configuration](../../admin/configuration/access-control/platform-managed-mode-configuration.md) -for setup instructions. -::: - ## Sections diff --git a/docs/user-guide/project-user-management/projects.md b/docs/user-guide/project-user-management/projects.md index 365ba697..ed4923d8 100644 --- a/docs/user-guide/project-user-management/projects.md +++ b/docs/user-guide/project-user-management/projects.md @@ -16,13 +16,6 @@ Platform Admins can view and manage all projects across the platform. To access Projects Management, click the **Profile** icon in the bottom-left corner → **Settings → Administration → Projects management**. -:::info Admin configuration required -Projects Management is only available when **Platform-managed mode** is enabled. If the -**Projects management** tab is not visible, ask your administrator to follow the -[Platform-managed Mode Configuration](../../admin/configuration/access-control/platform-managed-mode-configuration.md) -guide. -::: - ## Projects List The projects list displays all projects you have access to. For each project, the table shows: diff --git a/docs/user-guide/project-user-management/users.md b/docs/user-guide/project-user-management/users.md index f3be3545..841fa83c 100644 --- a/docs/user-guide/project-user-management/users.md +++ b/docs/user-guide/project-user-management/users.md @@ -15,13 +15,6 @@ The Users Management page is only accessible to **Platform Admins**. Regular use members within their own projects from the [Projects Management](./projects.md) page. ::: -:::info Admin configuration required -Users Management is only available when **Platform-managed mode** is enabled. If this tab -is not visible, ask your administrator to follow the -[Platform-managed Mode Configuration](../../admin/configuration/access-control/platform-managed-mode-configuration.md) -guide. -::: - The Users Management page gives Platform Admins a unified view of all users registered on the platform, their roles, and their project memberships. From here you can filter users, inspect individual user details, and manage project assignments. diff --git a/docs/user-guide/workflows/configuration/examples.md b/docs/user-guide/workflows/configuration/examples.md index 46ec7b63..cc30047b 100644 --- a/docs/user-guide/workflows/configuration/examples.md +++ b/docs/user-guide/workflows/configuration/examples.md @@ -1267,92 +1267,3 @@ execution_config: - Data validation and enrichment --- - -### 11.5 Example: Human-in-the-Loop Workflow (interrupt_before) - -This workflow demonstrates how to pause execution before a critical state and wait for -user review before proceeding. The pattern is based on the **Project Onboarding Kick-off** -template: the workflow generates an onboarding email, converts it to HTML, and then pauses -before sending — giving the user a chance to review and approve the final output. - ---- - -**Complete YAML Configuration:** - -```yaml -assistants: - - id: onboarding-writer - model: gpt-4.1 - system_prompt: | - Generate a welcome onboarding email for a new team member. - Ask for the recipient's name or email address first, then produce - the full email body following the standard onboarding template. - - - id: html-formatter - model: gpt-4.1 - system_prompt: | - Convert the provided email text into a responsive HTML email. - Do not change any text or titles. Output only the HTML code block. - - - id: email-sender - model: gpt-4.1 - tools: - - name: Email - system_prompt: | - Send the provided HTML email to the recipient. - Before sending, summarise the email details and ask for explicit - approval. Send only after the user confirms. - -states: - - id: write-email - assistant_id: onboarding-writer - task: | - Take the recipient's email address and generate the onboarding email. - next: - state_id: format-html - - - id: format-html - assistant_id: html-formatter - task: | - Transform the generated email text into a responsive HTML email. - next: - state_id: send-email - - - id: send-email - assistant_id: email-sender - task: | - Send the HTML email to the recipient's address. - interrupt_before: true # workflow pauses here — user reviews before sending - next: - state_id: end -``` - -**What happens at runtime:** - -1. `write-email` runs and generates the email text. -2. `format-html` converts it to HTML. -3. Before `send-email` executes, the workflow **pauses** and notifies the user. -4. The user reviews the prepared email and clicks **Continue** or **Abort**. -5. If continued, `send-email` dispatches the email via the Email tool. - -**Key concepts:** - -- `interrupt_before: true` on a state pauses the graph **before** that state runs — the - assistant has not executed yet, so no irreversible action has been taken. -- Place the interrupt **after analysis / generation and before the side-effecting action** - (sending email, creating tickets, running `terraform apply`, etc.). -- Only one `interrupt_before` state is needed per critical gate; chain multiple gates for - multi-step approval flows. -- The deprecated `wait_for_user_confirmation` key maps to the same behavior but should - not be used in new configurations. - -**When to use `interrupt_before`:** - -| Use it for | Avoid it for | -| -------------------------------------------------------------- | ---------------------------------------- | -| Sending emails or notifications | Read-only analysis steps | -| Creating or modifying Jira issues | Intermediate data transformations | -| Applying infrastructure changes (`terraform apply`, `kubectl`) | Low-risk, easily reversible operations | -| Any action the user should explicitly approve before it runs | Steps that run dozens of times in a loop | - ---- diff --git a/docs/user-guide/workflows/workflow-templates.md b/docs/user-guide/workflows/workflow-templates.md index bcb46bd4..d5a933bc 100644 --- a/docs/user-guide/workflows/workflow-templates.md +++ b/docs/user-guide/workflows/workflow-templates.md @@ -29,7 +29,7 @@ AI/Run CodeMie provides predefined workflow templates that serve as both example | Python Code Coverage Analysis Workflow | Example of a workflow that automates the checks for repository's code coverage and Jira ticket creation. | 1. Coverage Agent:
a) Plugin tool enabled
2. Jira Agent:
a) Generic Jira tool enabled | | Sequential Workflow Example | Example of sequential workflow. The first assistant finds all relevant information about workflow implementation and describes a business analyst as a requirements description. The second one provides a comprehensive description for QA engineers, support team, and users on how to use this specific aspect of the workflow functionality. | No extra tools required. | | Local Python Sonar Issues Fixer Workflow | Workflow for Fixing Sonar Issues | Git, Sonar, File Management | -| Project Onboarding Kick-off | Workflow for generating and sending out the project onboarding kick-off email to the new EPAM AI/Run CodeMie team member. The workflow will pause and ask the user to continue or abort the execution. | E-mail | +| Workflow With User Confirmation | The workflow will pause and ask the user to continue or abort the execution. | Jira, e-mail | | Sequential Workflow Example With Retry | Example of sequential workflow with customized retry policy on workflow level and on node level. If retry policy is specified on node level, then it will override workflow level. If none of retry policies are provided default retry policy will be utilized. | No extra tools required. | | Newsletter Generator | Workflow for generating and sending out to AI/Run CodeMie users the newsletter about the product release updates. | Release Summary Writer: Generic Jira
Hotfix Summarizer: Generic Jira
Newsletter Content Creator: Generic Jira
HTML Generating Assistant: Generic Jira
Email Sending Assistant: Email | | Autonomous Java Unit Tests Generation Workflow (PoC) | A workflow that automates the generation of unit tests for Java software within the AI/Run CodeMie platform. | JaCoCo report analyzer: Git, Plugin, Datasource
Define class coverage scenarios: Git, Plugin, Datasource | diff --git a/faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md b/faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md deleted file mode 100644 index b95b282d..00000000 --- a/faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md +++ /dev/null @@ -1,22 +0,0 @@ -# Can I limit how many projects a user can be assigned to? - -Yes. When Platform-managed mode is enabled, the `USER_PROJECT_LIMIT` environment variable -controls the maximum number of shared projects a regular user can be a member of. The -default is `3`. - -Set it in the `codemie-api` Helm chart `extraEnv`: - -```yaml -extraEnv: - - name: ENABLE_USER_MANAGEMENT - value: 'true' - - name: USER_PROJECT_LIMIT - value: '5' -``` - -Super Admins are always exempt from this limit and can access all projects regardless of -the configured value. - -## Sources - -- [Platform-managed Mode Configuration](https://codemie-ai.github.io/docs/admin/configuration/access-control/platform-managed-mode-configuration) diff --git a/faq/how-do-i-enable-project-and-user-management-in-codemie.md b/faq/how-do-i-enable-project-and-user-management-in-codemie.md deleted file mode 100644 index 43143b57..00000000 --- a/faq/how-do-i-enable-project-and-user-management-in-codemie.md +++ /dev/null @@ -1,33 +0,0 @@ -# How do I enable Project & User Management in AI/Run CodeMie? - -Project & User Management requires **Platform-managed mode** to be enabled by a platform -administrator. It is off by default. - -To enable it, set the following values in your Helm charts and redeploy both components: - -**`codemie-api` — `extraEnv`:** - -```yaml -extraEnv: - - name: ENABLE_USER_MANAGEMENT - value: 'true' - - name: USER_PROJECT_LIMIT - value: '3' -``` - -**`codemie-ui` — `values.yaml`:** - -```yaml -viteEnableUserManagement: true -viteEnableBudgetManagement: true -``` - -After applying both changes, the **Projects management** and **Users management** tabs -appear under **Settings → Administration** for users with the Admin role. - -If you are switching from an existing Keycloak-managed deployment, you also need to run a -one-time user migration — see the full guide for details. - -## Sources - -- [Platform-managed Mode Configuration](https://codemie-ai.github.io/docs/admin/configuration/access-control/platform-managed-mode-configuration) From 5d6fddc1c26506c3c2808d1b0a1dfb26679b5512 Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Wed, 20 May 2026 14:03:12 +0300 Subject: [PATCH 2/8] docs(config): restore files accidentally removed during squash --- .../platform-managed-mode-configuration.md | 72 +++++++++++++-- .../workflows/configuration/examples.md | 89 +++++++++++++++++++ .../workflows/workflow-templates.md | 2 +- ...many-projects-a-user-can-be-assigned-to.md | 22 +++++ ...-project-and-user-management-in-codemie.md | 33 +++++++ 5 files changed, 211 insertions(+), 7 deletions(-) create mode 100644 faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md create mode 100644 faq/how-do-i-enable-project-and-user-management-in-codemie.md diff --git a/docs/admin/configuration/access-control/platform-managed-mode-configuration.md b/docs/admin/configuration/access-control/platform-managed-mode-configuration.md index 428ce114..50d697b3 100644 --- a/docs/admin/configuration/access-control/platform-managed-mode-configuration.md +++ b/docs/admin/configuration/access-control/platform-managed-mode-configuration.md @@ -2,7 +2,7 @@ id: platform-managed-mode-configuration sidebar_position: 3 title: Platform-managed Mode Configuration -description: How to switch to Platform-managed mode and migrate existing Keycloak users +description: How to enable Platform-managed mode for fresh installations and when switching from Keycloak-managed mode pagination_prev: admin/configuration/access-control/access-control-overview pagination_next: null --- @@ -15,6 +15,13 @@ mode, where roles and project access are read from JWT claims on every request. For a comparison of both modes, see the [Access Control Overview](./index.md#deployment-modes). +## Deployment Scenarios + +| Scenario | Steps required | +| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| **Fresh installation** — deploying AI/Run CodeMie for the first time | [Step 1](#step-1-configure-helm-values) only | +| **Switching from Keycloak-managed mode** — existing deployment with users in Keycloak | [Step 1](#step-1-configure-helm-values) and [Step 2](#step-2-migrate-existing-keycloak-users-existing-deployments-only) | + ## Prerequisites - Access to the Kubernetes cluster and Helm values file of AI/Run CodeMie Backend and UI @@ -22,7 +29,7 @@ For a comparison of both modes, see the --- -## Step 1: Enable Platform-managed Mode +## Step 1: Configure Helm Values :::warning Both components must be updated The AI/Run CodeMie backend and the UI must be configured consistently. Enabling only one of them results @@ -31,17 +38,24 @@ in either missing UI controls or API errors. ### AI/Run CodeMie Backend -Set the `ENABLE_USER_MANAGEMENT` environment variable to `true` in the AI/Run CodeMie Backend -deployment. - -In the `codemie-api` Helm chart , add `ENABLE_USER_MANAGEMENT` to the `extraEnv` list: +In the `codemie-api` Helm chart, add the following variables to the `extraEnv` list: ```yaml extraEnv: - name: ENABLE_USER_MANAGEMENT value: 'true' + - name: USER_PROJECT_LIMIT + value: '3' ``` +`ENABLE_USER_MANAGEMENT` activates Platform-managed mode. When set to `true`, user roles +and project assignments are stored in the platform database and managed through the in-app +UI instead of being read from Keycloak JWT claims. + +`USER_PROJECT_LIMIT` sets the maximum number of shared projects a regular user can be +assigned to. Super Admins are always exempt from this limit. Adjust the value to match +your organisation's policy. + Apply the changes to the deployment. ### AI/Run CodeMie UI @@ -53,8 +67,16 @@ In the `codemie-ui` Helm chart `values.yaml`, set: ```yaml viteEnableUserManagement: true +viteEnableBudgetManagement: true ``` +`viteEnableUserManagement` tells the UI that Platform-managed mode is active. When set to +`true`, the **Users management** and **Projects management** tabs appear under +**Settings → Administration**. + +`viteEnableBudgetManagement` enables budget columns and the budget management section on +project detail pages. Set it to `false` if your deployment does not use budget tracking. + Apply the changes to the deployment. --- @@ -194,6 +216,44 @@ UPDATE users SET is_maintainer = true, is_admin = true WHERE email = ' -f values.yaml -n codemie + helm upgrade codemie-ui -f values.yaml -n codemie + ``` + +3. The `codemie-api` pod runs Alembic database migrations automatically on startup — no + manual database steps are required. The startup probe allows up to **600 seconds** for + migrations to complete. + + :::info Multiple replicas + If you run multiple `codemie-api` replicas, the migration runner acquires an exclusive + lock on the `alembic_version` table. Only the first replica to acquire the lock runs + the migration; the others wait and proceed once the lock is released. + ::: + +4. Verify the upgrade: log in as an admin and confirm the **Projects management** and + **Users management** tabs appear under **Settings → Administration**. + +--- + ## See Also - [API Configuration Reference — User Management Mode](../codemie/api-configuration.md#user-management-mode) diff --git a/docs/user-guide/workflows/configuration/examples.md b/docs/user-guide/workflows/configuration/examples.md index cc30047b..46ec7b63 100644 --- a/docs/user-guide/workflows/configuration/examples.md +++ b/docs/user-guide/workflows/configuration/examples.md @@ -1267,3 +1267,92 @@ execution_config: - Data validation and enrichment --- + +### 11.5 Example: Human-in-the-Loop Workflow (interrupt_before) + +This workflow demonstrates how to pause execution before a critical state and wait for +user review before proceeding. The pattern is based on the **Project Onboarding Kick-off** +template: the workflow generates an onboarding email, converts it to HTML, and then pauses +before sending — giving the user a chance to review and approve the final output. + +--- + +**Complete YAML Configuration:** + +```yaml +assistants: + - id: onboarding-writer + model: gpt-4.1 + system_prompt: | + Generate a welcome onboarding email for a new team member. + Ask for the recipient's name or email address first, then produce + the full email body following the standard onboarding template. + + - id: html-formatter + model: gpt-4.1 + system_prompt: | + Convert the provided email text into a responsive HTML email. + Do not change any text or titles. Output only the HTML code block. + + - id: email-sender + model: gpt-4.1 + tools: + - name: Email + system_prompt: | + Send the provided HTML email to the recipient. + Before sending, summarise the email details and ask for explicit + approval. Send only after the user confirms. + +states: + - id: write-email + assistant_id: onboarding-writer + task: | + Take the recipient's email address and generate the onboarding email. + next: + state_id: format-html + + - id: format-html + assistant_id: html-formatter + task: | + Transform the generated email text into a responsive HTML email. + next: + state_id: send-email + + - id: send-email + assistant_id: email-sender + task: | + Send the HTML email to the recipient's address. + interrupt_before: true # workflow pauses here — user reviews before sending + next: + state_id: end +``` + +**What happens at runtime:** + +1. `write-email` runs and generates the email text. +2. `format-html` converts it to HTML. +3. Before `send-email` executes, the workflow **pauses** and notifies the user. +4. The user reviews the prepared email and clicks **Continue** or **Abort**. +5. If continued, `send-email` dispatches the email via the Email tool. + +**Key concepts:** + +- `interrupt_before: true` on a state pauses the graph **before** that state runs — the + assistant has not executed yet, so no irreversible action has been taken. +- Place the interrupt **after analysis / generation and before the side-effecting action** + (sending email, creating tickets, running `terraform apply`, etc.). +- Only one `interrupt_before` state is needed per critical gate; chain multiple gates for + multi-step approval flows. +- The deprecated `wait_for_user_confirmation` key maps to the same behavior but should + not be used in new configurations. + +**When to use `interrupt_before`:** + +| Use it for | Avoid it for | +| -------------------------------------------------------------- | ---------------------------------------- | +| Sending emails or notifications | Read-only analysis steps | +| Creating or modifying Jira issues | Intermediate data transformations | +| Applying infrastructure changes (`terraform apply`, `kubectl`) | Low-risk, easily reversible operations | +| Any action the user should explicitly approve before it runs | Steps that run dozens of times in a loop | + +--- diff --git a/docs/user-guide/workflows/workflow-templates.md b/docs/user-guide/workflows/workflow-templates.md index d5a933bc..bcb46bd4 100644 --- a/docs/user-guide/workflows/workflow-templates.md +++ b/docs/user-guide/workflows/workflow-templates.md @@ -29,7 +29,7 @@ AI/Run CodeMie provides predefined workflow templates that serve as both example | Python Code Coverage Analysis Workflow | Example of a workflow that automates the checks for repository's code coverage and Jira ticket creation. | 1. Coverage Agent:
a) Plugin tool enabled
2. Jira Agent:
a) Generic Jira tool enabled | | Sequential Workflow Example | Example of sequential workflow. The first assistant finds all relevant information about workflow implementation and describes a business analyst as a requirements description. The second one provides a comprehensive description for QA engineers, support team, and users on how to use this specific aspect of the workflow functionality. | No extra tools required. | | Local Python Sonar Issues Fixer Workflow | Workflow for Fixing Sonar Issues | Git, Sonar, File Management | -| Workflow With User Confirmation | The workflow will pause and ask the user to continue or abort the execution. | Jira, e-mail | +| Project Onboarding Kick-off | Workflow for generating and sending out the project onboarding kick-off email to the new EPAM AI/Run CodeMie team member. The workflow will pause and ask the user to continue or abort the execution. | E-mail | | Sequential Workflow Example With Retry | Example of sequential workflow with customized retry policy on workflow level and on node level. If retry policy is specified on node level, then it will override workflow level. If none of retry policies are provided default retry policy will be utilized. | No extra tools required. | | Newsletter Generator | Workflow for generating and sending out to AI/Run CodeMie users the newsletter about the product release updates. | Release Summary Writer: Generic Jira
Hotfix Summarizer: Generic Jira
Newsletter Content Creator: Generic Jira
HTML Generating Assistant: Generic Jira
Email Sending Assistant: Email | | Autonomous Java Unit Tests Generation Workflow (PoC) | A workflow that automates the generation of unit tests for Java software within the AI/Run CodeMie platform. | JaCoCo report analyzer: Git, Plugin, Datasource
Define class coverage scenarios: Git, Plugin, Datasource | diff --git a/faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md b/faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md new file mode 100644 index 00000000..b95b282d --- /dev/null +++ b/faq/can-i-limit-how-many-projects-a-user-can-be-assigned-to.md @@ -0,0 +1,22 @@ +# Can I limit how many projects a user can be assigned to? + +Yes. When Platform-managed mode is enabled, the `USER_PROJECT_LIMIT` environment variable +controls the maximum number of shared projects a regular user can be a member of. The +default is `3`. + +Set it in the `codemie-api` Helm chart `extraEnv`: + +```yaml +extraEnv: + - name: ENABLE_USER_MANAGEMENT + value: 'true' + - name: USER_PROJECT_LIMIT + value: '5' +``` + +Super Admins are always exempt from this limit and can access all projects regardless of +the configured value. + +## Sources + +- [Platform-managed Mode Configuration](https://codemie-ai.github.io/docs/admin/configuration/access-control/platform-managed-mode-configuration) diff --git a/faq/how-do-i-enable-project-and-user-management-in-codemie.md b/faq/how-do-i-enable-project-and-user-management-in-codemie.md new file mode 100644 index 00000000..43143b57 --- /dev/null +++ b/faq/how-do-i-enable-project-and-user-management-in-codemie.md @@ -0,0 +1,33 @@ +# How do I enable Project & User Management in AI/Run CodeMie? + +Project & User Management requires **Platform-managed mode** to be enabled by a platform +administrator. It is off by default. + +To enable it, set the following values in your Helm charts and redeploy both components: + +**`codemie-api` — `extraEnv`:** + +```yaml +extraEnv: + - name: ENABLE_USER_MANAGEMENT + value: 'true' + - name: USER_PROJECT_LIMIT + value: '3' +``` + +**`codemie-ui` — `values.yaml`:** + +```yaml +viteEnableUserManagement: true +viteEnableBudgetManagement: true +``` + +After applying both changes, the **Projects management** and **Users management** tabs +appear under **Settings → Administration** for users with the Admin role. + +If you are switching from an existing Keycloak-managed deployment, you also need to run a +one-time user migration — see the full guide for details. + +## Sources + +- [Platform-managed Mode Configuration](https://codemie-ai.github.io/docs/admin/configuration/access-control/platform-managed-mode-configuration) From eb85ab724d015799abee117c950f6c7753140627 Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Wed, 20 May 2026 14:06:07 +0300 Subject: [PATCH 3/8] docs(config): restore files and row accidentally removed during squash --- docs/admin/configuration/codemie/api-configuration.md | 11 ++++++----- docs/user-guide/project-user-management/index.mdx | 9 +++++++++ docs/user-guide/project-user-management/users.md | 7 +++++++ 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index d79b3217..69d02736 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -554,11 +554,12 @@ Configure LiteLLM proxy for unified LLM access, budget management, and usage tra ### Proxy Mode -| Parameter | Type | Default | Description | -| ------------------- | ------- | ------------ | ------------------------------------------------------------------------------ | -| `LLM_PROXY_MODE` | string | `"internal"` | Proxy mode: `internal` (built-in routing), `lite_llm` (external LiteLLM proxy) | -| `LLM_PROXY_ENABLED` | boolean | `false` | Enable LLM proxy for centralized model access control | -| `LLM_PROXY_TIMEOUT` | integer | `300` | Max seconds to wait for proxy responses | +| Parameter | Type | Default | Description | +| ------------------------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `LLM_PROXY_MODE` | string | `"internal"` | Proxy mode: `internal` (built-in routing), `lite_llm` (external LiteLLM proxy) | +| `LLM_PROXY_ENABLED` | boolean | `false` | Enable LLM proxy for centralized model access control | +| `LLM_PROXY_TIMEOUT` | integer | `300` | Max seconds to wait for proxy responses | +| `LLM_PROXY_EMBEDDINGS_DISABLED` | boolean | `false` | When `true`, bypasses the LiteLLM proxy for embedding requests and sends them directly to the native provider (e.g., Azure OpenAI). Useful when LiteLLM does not support a required embedding model or when lower-latency direct access is preferred for vector operations. Has no effect when `LLM_PROXY_ENABLED=false` or `LLM_PROXY_MODE=internal`. | ### LiteLLM Connection diff --git a/docs/user-guide/project-user-management/index.mdx b/docs/user-guide/project-user-management/index.mdx index 9666ba67..79301541 100644 --- a/docs/user-guide/project-user-management/index.mdx +++ b/docs/user-guide/project-user-management/index.mdx @@ -19,6 +19,15 @@ users and their project memberships across the entire platform. The **Project & User Management** section is accessible via the **Profile** icon in the bottom-left corner → **Settings → Administration**. +:::info Admin configuration required +Project & User Management requires **Platform-managed mode** to be enabled by a platform +administrator. If you do not see the **Projects management** or **Users management** tabs +under **Settings → Administration**, contact your administrator. + +See [Platform-managed Mode Configuration](../../admin/configuration/access-control/platform-managed-mode-configuration.md) +for setup instructions. +::: + ## Sections diff --git a/docs/user-guide/project-user-management/users.md b/docs/user-guide/project-user-management/users.md index 841fa83c..f3be3545 100644 --- a/docs/user-guide/project-user-management/users.md +++ b/docs/user-guide/project-user-management/users.md @@ -15,6 +15,13 @@ The Users Management page is only accessible to **Platform Admins**. Regular use members within their own projects from the [Projects Management](./projects.md) page. ::: +:::info Admin configuration required +Users Management is only available when **Platform-managed mode** is enabled. If this tab +is not visible, ask your administrator to follow the +[Platform-managed Mode Configuration](../../admin/configuration/access-control/platform-managed-mode-configuration.md) +guide. +::: + The Users Management page gives Platform Admins a unified view of all users registered on the platform, their roles, and their project memberships. From here you can filter users, inspect individual user details, and manage project assignments. From b50b368d804abe72cb8205bba9e27d3c8d1c9cac Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Wed, 20 May 2026 14:08:55 +0300 Subject: [PATCH 4/8] docs(config): restore files and revert release notes change --- docs/admin/update/release-notes.md | 10 +++++----- docs/user-guide/project-user-management/projects.md | 7 +++++++ 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/admin/update/release-notes.md b/docs/admin/update/release-notes.md index 59a11709..2d8b8ab1 100644 --- a/docs/admin/update/release-notes.md +++ b/docs/admin/update/release-notes.md @@ -319,11 +319,11 @@ No third-party component updates in this release. Three new environment variables have been introduced to control LLM budget enforcement. All default to `false` (disabled): -| Variable | Default | Description | -| ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- | -| `LLM_PROXY_BUDGET_CHECK_ENABLED` | `false` | Enables LLM budget enforcement. When `true`, requests that exceed configured spending limits are blocked. | -| `LLM_PROXY_BUDGET_SYNC_ENABLED` | `false` | Syncs predefined budgets from `budgets-config.yaml` into the database on startup | -| `LLM_PROXY_BUDGET_BACKFILL_ENABLED` | `false` | Backfills user budget assignments from LiteLLM on startup for existing users | +| Variable | Default | Description | +| ----------------------------------- | ------- | -------------------------------------------------------------------------------- | +| `LLM_PROXY_BUDGET_CHECK_ENABLED` | `false` | Enables budget limit checking for LLM proxy requests | +| `LLM_PROXY_BUDGET_SYNC_ENABLED` | `false` | Syncs predefined budgets from `budgets-config.yaml` into the database on startup | +| `LLM_PROXY_BUDGET_BACKFILL_ENABLED` | `false` | Backfills user budget assignments from LiteLLM on startup for existing users | See [Budget Configuration](../configuration/extensions/litellm-proxy/budget-configuration.md) and [API Configuration](../configuration/codemie/api-configuration.md) for details. diff --git a/docs/user-guide/project-user-management/projects.md b/docs/user-guide/project-user-management/projects.md index ed4923d8..365ba697 100644 --- a/docs/user-guide/project-user-management/projects.md +++ b/docs/user-guide/project-user-management/projects.md @@ -16,6 +16,13 @@ Platform Admins can view and manage all projects across the platform. To access Projects Management, click the **Profile** icon in the bottom-left corner → **Settings → Administration → Projects management**. +:::info Admin configuration required +Projects Management is only available when **Platform-managed mode** is enabled. If the +**Projects management** tab is not visible, ask your administrator to follow the +[Platform-managed Mode Configuration](../../admin/configuration/access-control/platform-managed-mode-configuration.md) +guide. +::: + ## Projects List The projects list displays all projects you have access to. For each project, the table shows: From 9b1c247200252bcaba6143aff1c72a7756409076 Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Wed, 20 May 2026 15:28:37 +0300 Subject: [PATCH 5/8] docs(config): update release notes for 2.25.0 and 2.26.0 budget env vars --- docs/admin/update/release-notes.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/admin/update/release-notes.md b/docs/admin/update/release-notes.md index 2d8b8ab1..0963832e 100644 --- a/docs/admin/update/release-notes.md +++ b/docs/admin/update/release-notes.md @@ -188,9 +188,7 @@ No third-party component updates in this release.

Configuration Changes

-1. **Update LiteLLM budget env vars** — remove `LITELLM_SPEND_COLLECTOR_SCHEDULE` and set `LLM_PROXY_BUDGET_BACKFILL_ENABLED: "true"`. See [Budget Configuration](../configuration/extensions/litellm-proxy/budget-configuration.md). - -2. **One-time reconciliation via `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED`** +1. **One-time reconciliation via `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED`** :::warning One-time operation Enable only on a **single API replica**, wait for reconciliation to complete (check pod logs), then disable and scale replicas back. @@ -220,7 +218,15 @@ No third-party component updates in this release.

Configuration Changes

-No breaking configuration changes were introduced in this release. +1. **`LLM_PROXY_BUDGET_SYNC_ENABLED` and `LLM_PROXY_BUDGET_BACKFILL_ENABLED` removed** — both variables are replaced by `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED`. + + :::tip Configuration housekeeping + The following variables are no longer supported and should be removed from your `extraEnv`: + - `LLM_PROXY_BUDGET_SYNC_ENABLED` + - `LLM_PROXY_BUDGET_BACKFILL_ENABLED` + + Use `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED` instead. + :::

Known Issues

From 397a2dcfc63828c30d81b51e9c4629f307c89df4 Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Wed, 20 May 2026 16:43:52 +0300 Subject: [PATCH 6/8] docs(config): document spend tracking jobs and fix budget reconciliation description --- .../codemie/api-configuration.md | 16 ++-- .../litellm-proxy/budget-configuration.md | 83 +++++++++++++++++-- 2 files changed, 82 insertions(+), 17 deletions(-) diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index 69d02736..2d30587e 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -608,14 +608,14 @@ Caches user-to-budget resolution results to reduce database load on high-traffic Manages automatic reset of per-member budget windows aligned with LiteLLM's reset cycle. -| Parameter | Type | Default | Description | -| ---------------------------------------------------- | ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| `LITELLM_BUDGET_RESET_TRACKER_ENABLED` | boolean | `false` | Enables the background job that monitors soon-to-reset project budget windows. | -| `LITELLM_BUDGET_RESET_TRACKER_SCHEDULE` | string | `"*/10 * * * *"` | Cron schedule (UTC) for the reset-window tracker job. Defaults to every 10 minutes. | -| `LITELLM_BUDGET_RESET_WINDOW_MINUTES` | integer | `15` | Look-ahead window in minutes for detecting project budgets that will reset soon. | -| `LITELLM_BUDGET_RESET_RECONCILIATION_ENABLED` | boolean | `false` | Enables the daily reconciliation job that re-syncs reset state at midnight UTC. | -| `LITELLM_BUDGET_RESET_RECONCILIATION_SCHEDULE` | string | `"10 0 * * *"` | Cron schedule (UTC) for the reset reconciliation job. Must run within `LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES` of midnight. | -| `LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES` | integer | `10` | Allowed execution window in minutes after midnight UTC for the reconciliation job. | +| Parameter | Type | Default | Description | +| ---------------------------------------------------- | ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `LITELLM_BUDGET_RESET_TRACKER_ENABLED` | boolean | `false` | Enables the budget reset-window tracker job. Periodically checks which members have a budget reset approaching within the configured look-ahead window. | +| `LITELLM_BUDGET_RESET_TRACKER_SCHEDULE` | string | `"*/10 * * * *"` | Cron schedule (UTC) for the reset-window tracker job. Defaults to every 10 minutes. | +| `LITELLM_BUDGET_RESET_WINDOW_MINUTES` | integer | `15` | Look-ahead window in minutes. Members whose budget resets within this window are captured by the tracker job. | +| `LITELLM_BUDGET_RESET_RECONCILIATION_ENABLED` | boolean | `false` | Enables the daily reset reconciliation job. Runs shortly after midnight UTC and reconciles actual budget resets, correcting any mismatches between LiteLLM and CodeMie state. | +| `LITELLM_BUDGET_RESET_RECONCILIATION_SCHEDULE` | string | `"10 0 * * *"` | Cron schedule (UTC) for the reset reconciliation job. Must run within `LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES` of midnight. | +| `LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES` | integer | `10` | Allowed execution window in minutes after 00:00 UTC. The reconciliation schedule must run within this window — if not, the application will fail to start. | ### LiteLLM Spend Tracking diff --git a/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md b/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md index 59c7051a..d351bdc9 100644 --- a/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md +++ b/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md @@ -93,37 +93,102 @@ The `budget_category` field controls which type of usage the budget applies to: Budget enforcement is disabled by default. To activate it, set the following environment variables in the CodeMie API deployment: -| Variable | Type | Default | Description | -| ----------------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `LLM_PROXY_BUDGET_CHECK_ENABLED` | boolean | `false` | Enables LLM budget enforcement. When `true`, CodeMie actively enforces spending limits - LLM requests from users or projects that have exceeded their budget are blocked. Also enables budget API routes and background budget maintenance. | -| `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED` | boolean | `false` | Runs a post-startup reconciliation job that syncs predefined budgets from `budgets-config.yaml`, backfills user and project budget assignments, and aligns spending state with LiteLLM. Required for YAML budget definitions to take effect. | +| Variable | Type | Default | Description | +| ----------------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `LLM_PROXY_BUDGET_CHECK_ENABLED` | boolean | `false` | Enables LLM budget enforcement. When `true`, CodeMie actively enforces spending limits - LLM requests from users or projects that have exceeded their budget are blocked. Also enables budget API routes and background budget maintenance. | +| `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED` | boolean | `false` | Triggers a **one-time** reconciliation job on startup that syncs predefined budgets from `budgets-config.yaml`, backfills user and project budget assignments, and aligns spending state with LiteLLM. Must be disabled after reconciliation completes — it is not intended to stay enabled. | ### How budget enforcement works When `LLM_PROXY_BUDGET_CHECK_ENABLED` is enabled, CodeMie registers the budget enforcement provider and enables budget API routes. LLM requests are checked against active budgets - requests from users or projects that have exceeded their `max_budget` are rejected; requests approaching `soft_budget` generate warnings. -**Predefined budgets from `budgets-config.yaml` are not loaded by `LLM_PROXY_BUDGET_CHECK_ENABLED` alone.** To sync the YAML config into the database and LiteLLM, you must also set `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED=true`. The reconciliation job runs once after startup and: +**Predefined budgets from `budgets-config.yaml` are not loaded by `LLM_PROXY_BUDGET_CHECK_ENABLED` alone.** To sync the YAML config into the database and LiteLLM, run the one-time reconciliation by temporarily setting `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED=true`. The reconciliation job runs once after startup and: 1. Syncs predefined budgets from `budgets-config.yaml` into PostgreSQL and LiteLLM - config is the **source of truth**: existing budgets are created or updated, spending counters are preserved unless `budget_duration` changes 2. Syncs current spending state from LiteLLM back into CodeMie 3. Backfills budget assignments for existing users and projects -Without `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED=true`, changes to `budgets-config.yaml` never reach the database even after a pod restart. +Without running reconciliation, changes to `budgets-config.yaml` never reach the database even after a pod restart. -**In AI/Run CodeMie Backend values** (`values.yaml`): +### Running reconciliation + +Reconciliation is a one-time operation. Run it whenever you update `budgets-config.yaml` or on initial setup. + +When multiple replicas are running, a PostgreSQL advisory lock ensures only one pod executes the reconciliation — other pods acquire the lock, skip, and log `"Budget reconciliation lock held by another instance, skipping"`. You do not need to scale down to a single replica. + +1. Set `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED: "true"` in `extraEnv`. +2. Apply the Helm values and wait for pods to restart. +3. Confirm reconciliation completed successfully in pod logs. +4. Remove the variable (or set it to `"false"`) and re-apply. + +**In AI/Run CodeMie Backend values** (`values.yaml`) — enable budget enforcement permanently, run reconciliation once: ```yaml extraEnv: - name: LLM_PROXY_BUDGET_CHECK_ENABLED value: "true" + # Set to "true" temporarily during reconciliation, then remove - name: LLM_PROXY_BUDGET_RECONCILIATION_ENABLED value: "true" ``` -:::warning -`LLM_PROXY_BUDGET_RECONCILIATION_ENABLED` must be `true` for predefined budgets from `budgets-config.yaml` to be loaded into the database and LiteLLM. Without it, budget definitions in the config file have no effect even after a pod restart. +## Spend Tracking Background Jobs + +CodeMie includes background APScheduler jobs that collect spend data from LiteLLM, track upcoming budget resets, and reconcile daily resets. All three jobs are disabled by default and require `LLM_PROXY_ENABLED=true` to function. + +:::warning Prerequisite +All spend tracking jobs require the LiteLLM proxy to be enabled (`LLM_PROXY_ENABLED=true`). If any of these variables is set to `true` while `LLM_PROXY_ENABLED=false`, the scheduler will not start and a warning will be logged. +::: + +### Variables + +| Variable | Type | Default | Description | +| ---------------------------------------------------- | ------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `LITELLM_SPEND_COLLECTOR_ENABLED` | boolean | `false` | Enables the nightly spend collector job. Pulls spend data from LiteLLM and inserts rows into the spend tracking table. | +| `LITELLM_SPEND_COLLECTOR_SCHEDULE` | string | `0 23 * * *` | Cron schedule (UTC) for the spend collector. Default: every day at 23:00 UTC. | +| `LITELLM_BUDGET_RESET_TRACKER_ENABLED` | boolean | `false` | Enables the budget reset-window tracker job. Periodically checks which members have a budget reset approaching within the configured look-ahead window. | +| `LITELLM_BUDGET_RESET_TRACKER_SCHEDULE` | string | `*/10 * * * *` | Cron schedule (UTC) for the reset-window tracker. Default: every 10 minutes. | +| `LITELLM_BUDGET_RESET_WINDOW_MINUTES` | integer | `15` | Look-ahead window in minutes. Members whose budget resets within this window are captured by the tracker job. | +| `LITELLM_BUDGET_RESET_RECONCILIATION_ENABLED` | boolean | `false` | Enables the daily reset reconciliation job. Runs shortly after midnight UTC and reconciles actual budget resets, correcting any mismatches between LiteLLM and CodeMie state. | +| `LITELLM_BUDGET_RESET_RECONCILIATION_SCHEDULE` | string | `10 0 * * *` | Cron schedule (UTC) for the reconciliation job. Must be a daily schedule that falls within the midnight UTC window defined by `LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES`. | +| `LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES` | integer | `10` | Allowed execution window in minutes after 00:00 UTC. The reconciliation schedule must run within this window — if not, the application will fail to start. | + +### How each job works + +**Spend Collector** (`LITELLM_SPEND_COLLECTOR_ENABLED`) + +Runs nightly at 23:00 UTC. Queries LiteLLM for accumulated spend data across applications and inserts the results into the CodeMie spend tracking table. In a multi-replica deployment, an advisory lock ensures only one pod runs the job. + +**Budget Reset Tracker** (`LITELLM_BUDGET_RESET_TRACKER_ENABLED`) + +Runs every 10 minutes. Scans member budget reset windows and records which members are approaching a reset within the next `LITELLM_BUDGET_RESET_WINDOW_MINUTES` minutes. Keeps the budget reset state up to date between nightly reconciliations. + +**Budget Reset Reconciliation** (`LITELLM_BUDGET_RESET_RECONCILIATION_ENABLED`) + +Runs daily at 00:10 UTC (default). After budget periods roll over at midnight, this job verifies that all resets were applied correctly in both LiteLLM and CodeMie. It logs `updated`, `failed`, and `mismatch_warnings` counts on completion. + +:::info Schedule validation +When `LITELLM_BUDGET_RESET_RECONCILIATION_ENABLED=true`, CodeMie validates `LITELLM_BUDGET_RESET_RECONCILIATION_SCHEDULE` at startup. The schedule must be a daily cron expression and must fire within `LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES` minutes of midnight UTC. If validation fails, the application will not start. ::: +### Enabling all three jobs + +For a complete spend tracking setup, enable all three jobs together: + +**In AI/Run CodeMie Backend values** (`values.yaml`): + +```yaml +extraEnv: + - name: LITELLM_SPEND_COLLECTOR_ENABLED + value: "true" + - name: LITELLM_BUDGET_RESET_TRACKER_ENABLED + value: "true" + - name: LITELLM_BUDGET_RESET_RECONCILIATION_ENABLED + value: "true" +``` + +The three jobs are independent and can be enabled individually, but together they form a complete pipeline: the collector captures historical spend, the tracker monitors upcoming resets, and the reconciliation job corrects any state mismatches after midnight. + ## Customizing Budgets via Helm To override the default budget or add category-specific budgets, mount a custom `budgets-config.yaml` using the Helm chart's `extraVolumeMounts`, `extraVolumes`, and `extraObjects` values. From 2628d314a645aa86dfa1acbffdce8a39ae36d2d4 Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Wed, 20 May 2026 16:56:00 +0300 Subject: [PATCH 7/8] docs(config): add ui configuration section for budget management --- .../extensions/litellm-proxy/budget-configuration.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md b/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md index d351bdc9..6a8b700e 100644 --- a/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md +++ b/docs/admin/configuration/extensions/litellm-proxy/budget-configuration.md @@ -351,6 +351,18 @@ When `LITELLM_PREMIUM_MODELS_ALIASES` is set to an empty array (`'[]'`), premium The `/spending` endpoint returns an additional `premium_current_spending` field when this feature is enabled, so you can monitor premium model costs separately. +## UI Configuration + +### AI/Run CodeMie UI + +In the `codemie-ui` Helm chart `values.yaml`, set: + +```yaml +viteEnableBudgetManagement: true +``` + +`viteEnableBudgetManagement` enables budget columns and the budget management section on project detail pages. Set it to `false` if your deployment does not use budget tracking. + ## See Also - [LiteLLM Proxy Installation Guide](../../../deployment/extensions/litellm-proxy/index.md) From 80c03e2ced3ee4ab274f0c9b96b77152016e0094 Mon Sep 17 00:00:00 2001 From: Artem Zahumonnyi Date: Fri, 22 May 2026 11:16:04 +0300 Subject: [PATCH 8/8] fix(config): epmcdme-12316 fix inaccuracies in project-budget-management docs --- .../configuration/codemie/project-budget-management.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/admin/configuration/codemie/project-budget-management.md b/docs/admin/configuration/codemie/project-budget-management.md index 65d6702b..caad6b6e 100644 --- a/docs/admin/configuration/codemie/project-budget-management.md +++ b/docs/admin/configuration/codemie/project-budget-management.md @@ -93,7 +93,7 @@ When a project budget is created, CodeMie automatically distributes the budget e ### Equal allocation (default) -- `max_budget` and `soft_budget` are divided equally among all members using precise decimal arithmetic (9 decimal places). +- `max_budget` and `soft_budget` are divided equally among all members using precise decimal arithmetic. - Values are rounded to the nearest cent for display and enforcement. - If a rounding remainder exists (e.g., `$0.01` that cannot be split evenly), it is assigned to the last member determined by ascending `user_id` sort order. - The total of all member allocations never exceeds the project budget. @@ -174,12 +174,13 @@ Spend data updates on the collect schedule (nightly by default). There is typica ## Background Jobs and Environment Variables -Two background jobs maintain budget state. All jobs use PostgreSQL advisory locks so only one pod runs each job in a multi-replica deployment. +Three background jobs maintain budget state. All jobs use PostgreSQL advisory locks so only one pod runs each job in a multi-replica deployment. | Job | Purpose | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Spend collector** (`litellm_spend_collector`) | Polls LiteLLM for spend data and writes deltas to `project_spend_tracking` | | **Budget reset tracker** (`litellm_budget_reset_tracker`) | Detects budget period rollovers and adjusts spend records accordingly | +| **Budget reset reconciliation** | Runs daily after midnight UTC: verifies all budget resets were applied correctly in both LiteLLM and CodeMie | | **Startup reconciliation** | One-time on pod start: aligns DB state with LiteLLM (predefined budgets, user assignments, project budget assignments) | ### Environment variables @@ -190,6 +191,7 @@ Two background jobs maintain budget state. All jobs use PostgreSQL advisory lock | `LITELLM_SPEND_COLLECTOR_SCHEDULE` | `0 23 * * *` | Cron expression (UTC) for the spend collector. See [API Configuration](../api-configuration) for details. | | `LITELLM_BUDGET_RESET_TRACKER_ENABLED` | `false` | Enable the budget reset tracker background job | | `LITELLM_BUDGET_RESET_TRACKER_SCHEDULE` | `*/10 * * * *` | Cron expression (UTC) for the reset tracker | +| `LITELLM_BUDGET_RESET_RECONCILIATION_ENABLED` | `false` | Enable the daily budget reset reconciliation background job | | `LLM_PROXY_BUDGET_RECONCILIATION_ENABLED` | `false` | Enable one-time startup reconciliation on pod start | | `LLM_PROXY_BUDGET_RECONCILIATION_TIMEOUT_SECONDS` | `600` | Timeout in seconds for the startup reconciliation job | @@ -204,7 +206,7 @@ extraEnv: - name: LITELLM_BUDGET_RESET_TRACKER_ENABLED value: 'true' - name: LITELLM_BUDGET_RESET_TRACKER_SCHEDULE - value: '0 0 * * *' + value: '*/10 * * * *' - name: LLM_PROXY_BUDGET_RECONCILIATION_ENABLED value: 'true' ```