UMAI Platform documentation

Organization

The organization is the highest governance boundary in UMAI. It owns the license, the top-level audit scope, the operator workspace, and the identity binding used by Control Center.

• Use one organization per legal or operating boundary.
• Keep the organization ID aligned with the signed UMAI license.
• Directory access and audit evidence roll up to this level.

Environment

An environment represents a runtime boundary such as production, staging, a region, or a cluster. It separates deployment context, operational visibility, and rollout stages.

• Common IDs: `prod`, `staging`, `prod-eu`.
• Use environments when runtime boundaries differ.
• Keep environment IDs stable because they appear in logs and audit records.

Project

A project is the working unit for application integration. API keys, project dashboards, alerts, evaluations, and guardrail publishing are all project-scoped.

• Use one project per governed application surface or owning team.
• Create separate projects when API keys, monitoring, or policy ownership should differ.

Policies and Guardrails

A policy is a single rule. A guardrail is the deployable runtime package that groups policies with preflight and versioning. Operators author policies first, then assemble and publish guardrails.

• Policies are reusable building blocks.
• Guardrails are what your application actually calls at runtime.
• Publishing a guardrail creates the version used by UMAI Engine.

UMAI Control Center

• Operator-facing web UI for onboarding, policies, guardrails, evaluations, API keys, monitoring, alerts, and audit review.
• Authenticates browser users against LDAP or Active Directory.
• Proxies browser actions to UMAI Service through same-origin admin and public routes.

UMAI Service

• Stores organizations, environments, projects, policies, guardrails, API keys, evaluations, alerts, and audit records.
• Connects to the external database and external Redis.
• Validates the signed license and resolves the runtime guardrail that should be executed.

UMAI Engine

• Internal evaluation component used for runtime guardrail decisions.
• Reads published guardrail snapshots from Redis.
• Calls the approved inference endpoint for context-aware policies.

External dependencies

• Database: PostgreSQL, SQL Server, or Oracle.
• Redis: required for published guardrail snapshots.
• LDAP or Active Directory: required for Control Center operator sign-in.
• OpenAI-compatible inference endpoint: used when a policy needs model reasoning.

Recommended network exposure

Expose one HTTPS hostname for Control Center and one HTTPS hostname for runtime API traffic. Keep UMAI Engine private. Operators should never call the Engine directly from a browser.

• Operator browser -> UMAI Control Center.
• Application runtime -> UMAI Service public API.
• UMAI Service -> database, Redis, and UMAI Engine.
• UMAI Control Center -> LDAP or Active Directory.

Release packaging pattern

The clean enterprise pattern is vendor-controlled image distribution, internal registry mirroring, signed local license validation, and deployment only from approved internal infrastructure.

• Mirror images into Harbor, ECR, ACR, or Artifact Registry.
• Mount the signed `license.json` locally.
• Keep image tags and digests aligned across environments.

Authentication flow

A standard sign-in request follows a predictable sequence.

• The operator opens `/login` on UMAI Control Center.
• Control Center posts the username and password to the login endpoint.
• UMAI validates the credentials against LDAP or Active Directory.
• If group restrictions are configured, UMAI verifies group membership before issuing a session.
• The operator is redirected into the workspace or onboarding flow.

Recommended directory setup

Use a dedicated read-only bind account for directory search instead of relying on anonymous search. Restrict access to a well-defined operator group.

• Use `ldaps://` whenever possible.
• Define a narrow `LDAP_USER_SEARCH_BASE`.
• Set `LDAP_ALLOWED_GROUPS` for Control Center access control.
• Import the directory CA into the Control Center trust store when required.

What to validate before go-live

• A valid operator can sign in with username or email format accepted by the directory.
• A non-member of the allowed group is denied access cleanly.
• A bad password returns a clear login error instead of a redirect loop.
• TLS trust is working and does not depend on manual browser exceptions.

Common LDAP failure points

• Incorrect search base or bind DN.
• Directory certificate not trusted by the container.
• Group filter too broad or too narrow.
• Firewall rules blocking port 389 or 636 from Control Center.

If the deployment is prebound

• The operator signs in and is placed directly inside the predefined organization.
• The organization name, plan, and expiry match the licensed deployment.
• The operator can immediately create or open environments and projects.

If the workspace is created inside Control Center

• Create the organization first.
• Create the environment that represents the deployment boundary.
• Create the first project that the application will use for runtime integration.
• Verify that IDs are readable because they flow into logs, URLs, and API usage.

Scope

Create API keys inside the project that will own the runtime traffic. This keeps usage, alerts, and audit evidence tied to the correct application boundary.

Handling

UMAI shows the full secret only once at creation time. After that, operators see only a preview and revocation status.

Security posture

Store keys only in server-side secrets management. Never place them in browser code, mobile clients, or shared frontend bundles.

How to create an API key

• Open the target project in Control Center.
• Go to `API Keys`.
• Create a new secret key and give it a recognizable name.
• Copy the value immediately and store it in a secret manager.
• Use one key per runtime or service so revocation is clean.

Rotation and revocation

• Create the replacement key before revoking the old one.
• Roll out the new key through deployment secrets.
• Verify live runtime traffic with the new key.
• Revoke the old key from the project key list.

Heuristic policy

Use heuristic policies for pattern-based controls such as identifiers, prompt injection indicators, forbidden phrases, or deterministic data classes.

Context-aware policy

Use context-aware policies when intent matters and the rule requires model reasoning rather than pattern matching.

Scope and phase

Policies can be scoped to project, environment, or organization and can run in PRE_LLM, POST_LLM, or both phases depending on the use case.

Create a policy in Control Center

• Open the target project and go to `Policies`.
• Use the `Create` tab for a new policy, `Templates` for a starter, or `Existing` to review what is already live.
• Describe the rule in plain language and review the generated draft.
• Set the policy name, policy ID, scope, enabled state, and phases.
• Review the config preview and example decisions before creating the policy.
• Attach the new policy to a guardrail after creation.

Good policy authoring practice

• Keep each policy focused on one control objective.
• Use heuristic rules where precision is pattern-based and low latency matters.
• Use context-aware rules only when the decision truly depends on semantics.
• Document examples that explain both ALLOW and BLOCK behavior.

Guardrail modes

Use `ENFORCE` when the runtime should actively block or modify traffic based on policy outcomes. Use `MONITOR` when you want visibility first and enforcement later.

Versioning and publish

Guardrails are versioned. Create a new version when policy membership, preflight rules, or LLM settings change. Publishing updates the runtime snapshot used by the Engine.

Preflight checks

Preflight defines what content is inspected before policy execution, such as the last user message or the broader conversation context.

Policy assembly

A guardrail can include multiple policies. The quality of a guardrail depends on choosing the right policy mix, phases, and runtime mode for the workflow it protects.

Create a guardrail in Control Center

• Open the target project and go to `Guardrails`.
• Start from `Templates` if a built-in pattern matches your use case, or use the guided builder to create a bespoke guardrail.
• Choose whether you are creating a new guardrail or a new version of an existing one.
• Set the guardrail name, ID, mode, and phases.
• Attach the policies that should run inside the guardrail.
• Review preflight behavior, LLM configuration, version number, and publish choice.
• Create the version and publish it so the runtime snapshot becomes active.

What a strong first guardrail looks like

• Covers one well-defined workflow or application surface.
• Uses a small, understandable set of policies.
• Starts in `MONITOR` if the team still needs to tune false positives.
• Includes representative test prompts before the API key is handed to developers.

How to run an evaluation

• Open the target project and go to `Evaluation`.
• Choose the guardrail and phase you want to measure.
• Use a preset evaluation set or upload a custom JSONL dataset.
• Give the run a name so it is easy to compare later.
• Start the run and wait for processing to complete.
• Review grade, action accuracy, block rate, confusion data, and sample cases.

When to run evaluations

• Before first production rollout.
• After policy additions or removals.
• After changing preflight or LLM settings.
• When false positives or false negatives are reported by operators.

Grade

A high-level summary of how closely the guardrail matches the expected actions in the evaluation dataset.

Action accuracy

Measures how often the actual action matched the expected action label for the supplied cases.

Sample results

Shows where the guardrail matched or missed expectations so operators can tune policies instead of guessing.

How to test a guardrail

• Open the target project and go to `Test`.
• Select the guardrail and the version you want to inspect.
• Choose `PRE_LLM` or `POST_LLM`.
• Add one or more conversation messages and pick the correct phase focus.
• Run the test and inspect the decision, latency, and triggering policy details.
• Repeat with safe, borderline, and intentionally bad examples.

Good test cases

• A clearly safe prompt that should be allowed.
• A known-sensitive prompt containing an identifier or restricted data class.
• A prompt injection attempt that tries to override prior instructions.
• A multilingual example if the workflow handles more than one language.

Recommended integration sequence

• Publish the target guardrail from Control Center.
• Create a project API key and store it in server-side secrets management.
• Call the runtime endpoint with the correct `guardrail_id` and phase.
• Honor the returned decision in your application flow.
• Log the `request_id` so operators can correlate runtime behavior with UMAI dashboards.

Good integration rules

• Keep API keys off the frontend.
• Use one guardrail ID per governed workflow when possible.
• Treat PRE_LLM and POST_LLM as different control points.
• Fail safely when the workflow depends on a hard enforcement boundary.

Sync guardrail calls

Best for inline chat, agent prompts, and other places where a single decision must be returned before the workflow continues.

Async patterns

Use async integration patterns for longer-running agent flows or tool chains that should continue while a guardrail job is evaluated.

Implementation guides

Control Center includes implementation guides for the UMAI Browser Extension, OpenAI Agents SDK, Google ADK, Claude, xAI, and LangChain.

Monitoring page

The Monitoring page summarizes how the project is behaving over recent traffic windows.

• Number of threats detected.
• Usage trend and alerted-request trend.
• Detection rate across observed requests.
• Top threat categories and recent alerts.

Alerts page

The Alerts page is the review console for blocked and flagged traffic.

• Search and filter by issue, policy, request, or decision.
• Inspect severity, phase, guardrail, latency, and timestamps.
• Open the detailed alert panel for workflow, metadata, and matched rule context.

What operators should watch

• Unexpected spikes in detection rate after a new guardrail version.
• High-volume categories that suggest the wrong policy boundary.
• Repeated flagged traffic that should become enforced traffic.
• Latency trends that suggest a context-aware policy needs tuning.

What analysts should review

• Which policy triggered the decision.
• Whether the project is in `MONITOR` or `ENFORCE` mode for the workflow.
• Whether the alert pattern points to a missing policy or bad application behavior.

What is recorded

Audit events can include action, phase, guardrail ID, guardrail version, decision severity, reason, request ID, redaction state, message context, and hashes used for event chaining.

Why it matters

The Audit Ledger supports incident review, policy tuning, governance reporting, and evidence reconstruction without asking application teams to keep separate parallel records.

Evidence packs

Operators can export JSONL audit streams and generate evidence packs for regimes such as EU AI Act, GDPR, CPRA ADMT, SEC Cyber, or custom frameworks.

How it is deployed

Deploy the extension through managed browser policy so installation, configuration, and update control stay with IT and security teams.

What it does

The extension can evaluate prompt attempts, apply allow, warn, block, redact, or justify actions before submit, and upload governed usage events for central review.

Where it shows up

Extension activity feeds into UMAI monitoring and extension event views so browser usage sits beside runtime governance instead of becoming a separate blind spot.

Typical browser extension rollout

• Force-install the extension through managed Chrome or Edge policy.
• Push tenant and policy configuration through managed browser settings.
• Start in metadata-only capture or warning mode if the organization wants a phased rollout.
• Move to block or redact once reviewed usage patterns are understood.

Where it fits in the platform

• Use runtime guardrails for governed internal applications and APIs.
• Use the Browser Extension for unmanaged browser AI usage outside those apps.
• Review both in the same UMAI governance operating model.

Login page loads but sign-in fails

Check LDAP URL, bind credentials, search base, allowed groups, and certificate trust first.

Service `readyz` reports degraded state

Validate the database DSN, runtime database user, Redis ACLs, and Engine connectivity before changing anything else.

Policies exist but runtime behavior does not change

Confirm the relevant guardrail version was created and published. Editing a policy alone does not update runtime behavior until the guardrail version is published.

Guardrail tests fail from Control Center

Check the selected phase, guardrail version, Engine availability, Redis snapshot presence, and the default LLM configuration if context-aware policies are involved.

Application requests fail with auth errors

Verify the project API key, guardrail ID, deployment hostname, and whether the application is sending the request from trusted server-side code.

Alerts spike after a release

Compare the new guardrail version, policy membership, preflight settings, and evaluation results against the prior version before rolling back.