Skip to main content

B12 - Model Evaluation

GroupTechnologyStatusServiceRoadmap phaseContracts
B - LLM management and Model GatewayRagas + Promptfooopen source integratedevaluations8evaluation-contract

Back to index - Français

Role and responsibilities​

Benchmarks candidate models and gates status promotion to approved.

Data model​

Tables (schema eai, every tenant table carries tenant_id uuid NOT NULL with an RLS policy on current_setting('app.tenant_id', true)::uuid): eai.eval_runs, eai.eval_suites, eai.audit_events.

API endpoints​

  • POST /v1/evaluations/runs
  • GET /v1/evaluations/runs/{id}
  • POST /v1/evaluations/gates/check
POST /v1/evaluations/runs HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: en
Content-Type: application/json

{"suite_id": "3a8bdb8e-858a-4619-9832-3c86fa476f2a", "trigger": "manual", "outputs": ["Refunds are accepted within 30 days of purchase."]}
{"schema_version": "1.0", "evaluation_id": "27569be4-49d7-4bb6-a7ea-b458ee836c5f", "tenant_id": "18de5695-21f9-4053-a4ea-beb4bf2a5932", "name": "support-answers", "target": {"type": "model", "ref": "fake-gpt"}, "engine": "custom", "kind": "quality", "dataset": {"ref": "support-golden", "size": 1, "digest": "sha256:0ce686fcfa2070052c234bd1db464e4994992c453859b3dad1ee3351cf26928a", "version": "1"}, "metrics": [{"name": "contains", "threshold": 0.8, "comparator": "gte"}], "gate": {"blocking": true}, "results": [{"value": 1.0, "metric": "contains", "passed": true, "samples": 1}], "status": "passed", "started_at": "2026-10-30T01:38:14.674524Z", "finished_at": "2026-10-30T01:38:14.674524Z", "cost": {"amount": "0", "currency": "USD"}, "run_id": "27569be4-49d7-4bb6-a7ea-b458ee836c5f", "suite_id": "3a8bdb8e-858a-4619-9832-3c86fa476f2a", "trigger": "manual", "case_results": [{"index": 0, "scores": {"contains": 1.0}}], "error": null}

Errors use the common envelope {"error": {"code", "message", "message_i18n", "details", "request_id"}}; lists are paginated with limit and cursor.

SDK usage​

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.evaluation.list_suites()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.evaluations.listSuites();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.evaluations().listSuites();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Evaluations.ListSuites(ctx)

Configuration​

  • Environment: EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
  • Helm values: controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config.

Security controls​

  • Authentication by OIDC JWT, tenant API key with scopes, or SPIFFE mTLS; tenant resolved from the credential, never from the body.
  • Authorization through OpenFGA and OPA decisions; every mutation and decision writes a hash-chained eai.audit_events row.
  • Secrets never returned by the API; TLS everywhere; Cilium network policies restrict who can reach the service.

Observability​

  • Metrics: eai_model_evaluation_requests_total, eai_model_evaluation_errors_total, eai_model_evaluation_latency_seconds (Prometheus).
  • Traces: OpenTelemetry spans eai.evaluations.* with W3C traceparent propagation, AI spans forwarded to Opik.
  • Audit actions: evaluation.suite.create, evaluation.run, evaluation.gate.check, redteam.run, policy.evaluate.

FinOps aspects​

Operating cost is allocated per tenant and project through labels on Usage Events and Kubernetes resource requests; no direct per-call cost.

Failure modes and resilience​

  • Stateless replicas behind the API Gateway, PostgreSQL HA for state; readiness probe GET /readyz removes unhealthy pods.
  • External system unavailable: fail closed for security decisions, explicit error code, no silent bypass.

Standalone adoption (client of a client)​

A client of a client can adopt this brick alone with the Python SDK sub-client client.evaluation (TS eai.evaluations, Java client.evaluations(), Go client.Evaluations). Minimal deployment: Control Plane API + PostgreSQL + Keycloak (or API keys), the Control Plane loads every domain of services/control-plane/src/eai/domains; the optional chart components are switched off in deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Acceptance tests​

  1. A tenant cannot read or modify another tenant's resources (RLS test).
  2. Every mutation produces an audit event verifiable by GET /v1/audit/verify.
  3. Errors are returned in English and French according to Accept-Language.

A/B comparisons and baselines (LLM_-013)​

POST /v1/evaluations/comparisons runs the same suite on the baseline and on the candidate (model or version) with the existing engines, then saves in eai.eval_comparisons (V138) both runs, the per metric deltas and the verdict (candidate_better, equivalent, regression, inconclusive, per tolerance). Tests: tests/test_evaluation_ab.py.