veylant/docs/admin-guide.md

# Veylant IA — Admin User Guide

This guide covers day-to-day administration of the Veylant IA platform. All operations require an admin JWT.

## 1. Overview

The Veylant IA admin dashboard exposes a REST API under `/v1/admin/`. Key capabilities:

| Area | Endpoints |
|---|---|
| Routing policies | `/v1/admin/policies` |
| Audit logs | `/v1/admin/logs` |
| Cost reporting | `/v1/admin/costs` |
| User management | `/v1/admin/users` |
| Feature flags | `/v1/admin/flags` |
| Provider status | `/v1/admin/providers/status` |
| Rate limits | `/v1/admin/rate-limits` |
| GDPR/Compliance | `/v1/admin/compliance/*` |

Interactive documentation: **[GET /docs](http://localhost:8090/docs)**

---

## 2. Routing Policy Management

Routing policies control which AI provider receives each request, based on department, role, model, or sensitivity.

### List policies

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/policies
```

### Create a policy

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR to GPT-4o mini",
    "priority": 10,
    "is_enabled": true,
    "conditions": [
      {"field": "department", "operator": "eq", "value": "HR"}
    ],
    "action": {"provider": "openai", "model": "gpt-4o-mini"}
  }' \
  http://localhost:8090/v1/admin/policies
```

### Seed a template

Pre-built templates for common use cases:

```bash
# Available: hr, finance, engineering, catchall
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/policies/seed/hr
```

### Priority order

Rules are evaluated in ascending priority order — lower number = higher priority. The first matching rule wins. Configure a `catchall` rule with high priority (e.g. 999) as a fallback.

### Disable routing engine for a tenant

Set `routing_enabled=false` to bypass the rules engine and use static prefix routing:

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -d '{"enabled": false}' \
  http://localhost:8090/v1/admin/flags/routing_enabled
```

---

## 3. Audit Logs

All requests are logged to ClickHouse. Query via the admin API:

```bash
# Last 50 entries
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/logs"

# Filter by provider and time range
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/logs?provider=openai&start=2026-01-01T00:00:00Z&limit=100"

# Filter by minimum sensitivity
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/logs?min_sensitivity=high"
```

**Sensitivity levels**: `low` | `medium` | `high` | `critical` (based on PII entity types detected).

### CSV export

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/compliance/export/logs" -o audit-export.csv
```

---

## 4. Cost Reporting

```bash
# Group by provider
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/costs?group_by=provider"

# Group by department
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/costs?group_by=department&start=2026-01-01T00:00:00Z"
```

Response includes `total_tokens`, `total_cost_usd`, and `request_count` per group.

### Disable billing tracking

If you do not want costs recorded for a tenant (e.g. during a trial period):

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -d '{"enabled": false}' \
  http://localhost:8090/v1/admin/flags/billing_enabled
```

---

## 5. User Management

```bash
# List users
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/users

# Create a user
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@corp.example",
    "first_name": "Jane",
    "last_name": "Doe",
    "department": "Finance",
    "role": "user"
  }' \
  http://localhost:8090/v1/admin/users

# Update role
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "manager"}' \
  http://localhost:8090/v1/admin/users/{id}

# Soft-delete a user
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/users/{id}
```

**Roles**: `admin` | `manager` | `user` | `auditor`

RBAC rules:
- `admin`: full access to all models and admin API
- `manager`: access to all user-allowed models + audit read access
- `user`: restricted to `user_allowed_models` from the RBAC config
- `auditor`: read-only access to logs and costs, cannot use the proxy

---

## 6. Feature Flags

Feature flags let you toggle module-level behaviour per tenant without a restart.

### Built-in flags

| Flag | Default | Effect when false |
|---|---|---|
| `pii_enabled` | `true` | Skips PII anonymization entirely |
| `routing_enabled` | `true` | Uses static prefix routing instead of rules engine |
| `billing_enabled` | `true` | Sets `cost_usd = 0` in audit entries |
| `zero_retention` | `false` | PII service does not persist mappings in Redis |

```bash
# List all flags (tenant + global)
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/flags

# Disable PII for this tenant
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -d '{"enabled": false}' \
  http://localhost:8090/v1/admin/flags/pii_enabled

# Re-enable (or remove tenant override to fall back to global default)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/flags/pii_enabled
```

---

## 7. Provider Status

Check the circuit breaker state of each upstream provider:

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/providers/status
```

States: `closed` (healthy) | `open` (failing, requests rejected) | `half-open` (testing recovery).

---

## 8. Rate Limit Configuration

```bash
# View current config
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/rate-limits/{tenant_id}"

# Update limits (takes effect immediately, no restart needed)
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests_per_min": 2000,
    "burst_size": 400,
    "user_rpm": 200,
    "user_burst": 40,
    "is_enabled": true
  }' \
  "http://localhost:8090/v1/admin/rate-limits/{tenant_id}"

# Remove custom config (reverts to global default)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/rate-limits/{tenant_id}"
```

---

## 9. GDPR / EU AI Act Compliance

### Processing Registry (Article 30)

```bash
# List processing activities
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/compliance/entries

# Create a new processing activity
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "use_case_name": "Chatbot RH",
    "legal_basis": "legitimate_interest",
    "purpose": "Automatisation des réponses RH internes",
    "data_categories": ["identifiers", "professional"],
    "recipients": ["HR team"],
    "processors": ["OpenAI Inc."],
    "retention_period": "12 months",
    "security_measures": "AES-256 encryption, access control",
    "controller_name": "Acme Corp DPO"
  }' \
  http://localhost:8090/v1/admin/compliance/entries
```

### EU AI Act Classification

Classify an entry by answering 5 risk questions:

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_act_answers": {
      "q1": false,
      "q2": false,
      "q3": true,
      "q4": false,
      "q5": true
    }
  }' \
  "http://localhost:8090/v1/admin/compliance/entries/{id}/classify"
```

Risk levels: `minimal` (0 yes) | `limited` (1-2 yes) | `high` (3-4 yes) | `forbidden` (5 yes).

### GDPR Rights

```bash
# Art. 15 — Data subject access request
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/compliance/gdpr/access/user@corp.example"

# Art. 17 — Right to erasure
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/compliance/gdpr/erase/user@corp.example?reason=user-request"
```

The erasure endpoint soft-deletes the user and creates an immutable audit record. It is safe to call even without a database connection (graceful degradation).

---

## 10. Health & Monitoring

```bash
# Service health (no auth required)
curl http://localhost:8090/healthz

# Prometheus metrics (if enabled)
curl http://localhost:8090/metrics
```

Metrics expose request counts, latency histograms, and error rates per model/provider.