PeopleLens AI

Governed People Analytics with an AI that knows what it must not answer.

An authorial project by LevelInteligencIA — People Analytics · Data Engineering · Data Quality · Data Governance · AI/MCP.

351 tests passing · 35 ADRs · 18 KPI contracts · 87 data quality checks · 6 MCP capabilities

1. What is PeopleLens AI?

PeopleLens AI turns heterogeneous, inconsistent, low-quality HR data into a governed analytical layer, and exposes it through a natural-language interface that knows what it can answer and, more importantly, what it cannot.

The difference from a typical "chat with your HR data" demo is the direction of authority. Here, the AI never defines a metric, never calculates one, and never decides whether an answer is trustworthy. It reads language and it communicates results. Everything in between is governed.

Related MCP server: agentic-ops-builder

2. The business problem

HR data rarely arrives ready. It comes from multiple systems, in different formats, with divergent names for the same concept, missing fields, duplicates, inconsistent IDs, invalid dates and broken referential integrity. On top of that, organizations change: the same area changes name, structure and owner across the years.

The practical result is familiar to anyone who has led People Analytics:

• every analyst calculates turnover slightly differently;

• nobody can say where a number came from;

• leadership stops trusting the function.

Adding an LLM to that foundation does not solve the problem. It industrializes it, because now the wrong number arrives fluently and with confidence.

3. Core thesis

AI should not define or calculate People KPIs. People Analytics defines and governs them.

Everything in this repository follows from that sentence. The LLM is a semantic parser, not an analyst: it converts a question into a structured Intent and stops. It has no field in which to write SQL, a table name, a tool name or a number — not because it is forbidden, but because the contract has no such field.

4. Architecture

flowchart TD
    S[Source systems] --> R[Raw · immutable]
    R --> P[Profiling]
    P --> ST[Standardization]
    ST --> M[Mapping · DE/PARA]
    M --> DQ[Data Quality · 87 checks]
    DQ --> Q[Quarantine & Exceptions]
    Q --> AM[Analytical Model · L3]
    AM --> SL[Semantic / KPI Layer · L4]
    SL --> CK[Certified KPIs]
    CK --> MCP[MCP · 6 read-only capabilities]
    MCP --> AG[PeopleLens Agent]
    AG --> LLM[LLM Interpreter]

    style R fill:#1f2937,color:#fff
    style DQ fill:#1f2937,color:#fff
    style SL fill:#1f2937,color:#fff
    style MCP fill:#1f2937,color:#fff

Layered pipeline: L0 raw → L1 standardized → L2 conformed → L3 analytical → L4 semantic. Raw is immutable. Every transformed value keeps traceability to its original value, its source system and the rule applied.

5. Governance model

Six roles, one direction of authority. The LLM sits at the end of that chain, never at the start.

6. Trust model

Trust is a lattice, never an invented number:

trust_answer = min(trust_data, kpi_status_ceiling, actor_ceiling)

CERTIFIED is not computable. It is recorded human approval, with an owner and a date. A pipeline cannot promote itself.

Current KPI catalog: 5 CERTIFIED, 8 DECLARED, 5 BLOCKED — 18 contracts.

7. AI boundaries

What the LLM cannot reach, and why it structurally cannot:

The agent may investigate the data, but it cannot alter the truth of the data.

The LLM's output is treated as untrusted input (ADR-0035): it is validated locally even when the provider enforces a schema, and an unknown field rejects the entire Intent rather than being ignored.

8. Smart Refusal

A refusal is a result, not a protocol error — and never a closed door. Every refusal states what would resolve it.

The agent refuses when:

• the period is not supported by the KPI (wrong grain, outside coverage);

• a dimension or member is not in the governed vocabulary;

• the evidence does not sustain the requested response level;

• the KPI is blocked by governance.

Sixteen declared refusal classes, including KPI_BLOQUEADO, TERMO_DESCONHECIDO, GRAIN_INCOMPATIVEL, PERIODO_FORA_DE_COBERTURA, POPULACAO_ABAIXO_DO_MINIMO and NIVEL_SEM_EVIDENCIA.

The showcase case: "What was turnover for Tecnologia in Q2 2026?" returns zero data calls. turnover_rate is annual, so there is no quarterly version; and no department is called "Tecnologia". The answer offers the valid departments and the valid periods, and never silently resolves "Tecnologia" to "Engineering" — a wrongly mapped term is invisible, an unmapped one is visible.

9. MCP capabilities

Six, all read-only. No generic execute_sql, no query_database, no write.

Every response is an envelope with one of four outcomes: ANSWER, REFUSAL, SUPPRESSED, ERROR.

10. Agent loop

UNDERSTAND → RESOLVE → PLAN → ACT → OBSERVE → INTERPRET → DECIDE → RESPOND

There is deliberately no VALIDATE step. Trust, response ceiling, minimum-n and governed states arrive already decided in the envelope; a step called "validate" would invite the agent to re-evaluate what has been decided, and re-evaluating is halfway to disagreeing.

PLAN is an artifact, not reasoning (ADR-0034). It exists before the first MCP call, and each step declares capability, reason and objective. That is what makes "why did the agent call this?" answerable six months later.

Every execution ends with one of ten declared stop_reason values.

11. LLM Interpreter

Empirical evaluation: 16 of 17 cases, 4 of 4 PT-BR ↔ EN-US semantic equivalence, no fallback, no retry. The single case that failed exposed a contract gap rather than a model error — the model declined to invent a comparison base that the governed vocabulary did not declare, which is the correct behaviour. See docs/llm_interpreter_p03_report.md.

12. Demonstrated scenarios

Validated end-to-end with the real LLM and the real MCP.

Scenario D is the reason intent/1.1 exists. The earlier contract could only express relative comparison bases, so a question naming two periods silently fell back to "previous period" and compared 2024 against 2023. The fix was not to make the plan guess better: it was to let the contract carry both periods (RF-02).

13. Privacy

Suppression by minimum n, declared per KPI contract (currently 5 or 20 depending on the metric), plus complementary suppression so that a suppressed cell cannot be recovered by subtracting the visible ones.

The agent cannot work around it: the harness blocks the sequence of narrowing queries that would reconstruct a suppressed slice, and it blocks it before the call, not after.

14. Data quality

87 declared checks, run by a purpose-built runner — checks live in configuration, never in code.

Three attributes govern each check, answering three different questions: threshold (when it fails), severity (what happens to the failing row) and finding_class (what kind of problem it is).

Governance pendencies are named members, never nulls: UNMAPPED, DECISAO_PENDENTE, TRADUCAO_PENDENTE, SEM_CHAVE_DE_ORIGEM, FORA_DO_UNIVERSO, AINDA_NAO_OCORREU, ANTERIOR_A_SERIE, INDETERMINADA. A pending decision that hides as a null is a decision nobody will ever make.

15. Data lineage

KPI  →  business rule  →  analytical table  →  source system

get_lineage walks that chain, linked by trace_id across four logs: agent_run_log (why it was called) → mcp_call_log (who called) → semantic_query_log (what was asked) → l3_run_id (which load).

16. Synthetic data disclaimer

The dataset is entirely synthetic. It describes a fictional company, NOVAORA, with roughly ten years of HR history across five LATAM countries.

It does not represent any real company, country, population or demographic statistic. It was generated deliberately messy, to reproduce the data problems described in section 2 — and it was never optimized to produce favourable DEI results.

17. Bilingual product direction · Direcionamento bilíngue

The product is designed for PT-BR and EN-US. The same question in either language must produce the same semantic Intent: language changes neither the KPI, nor the period, nor the dimension, nor governance, nor the calculation.

Governed values are never translated. "Customer Service" stays "Customer Service" in both languages; display labels are an interface concern, not a licence for the model to invent or translate a dimension member.

Em português: o PeopleLens é desenhado para operar em PT-BR e EN-US. A equivalência semântica entre os dois idiomas foi validada empiricamente (4 de 4 pares). A camada de interface bilíngue está registrada como requisito futuro (RF-01) e ainda não foi implementada. A documentação de arquitetura do projeto está em português, em docs/.

18. Tech stack

19. Project status

Architecture and core agent flow implemented and validated.

ADRs 0024–0035 are recorded as Proposta (proposed) and await formal acceptance as a block.

20. Roadmap

Short and honest. None of the below is implemented.

• Interface / demo — there is no UI; the agent is exercised through the harness and scripts.

• RAG for governed definitions — ADR-0016 already limits RAG to context and definitions, never to numbers. Not built.

• Richer visual exploration — breakdowns and comparisons rendered visually.

• Bilingual interface layer (RF-01) — registered, not implemented.

• Wave 2 source systems — the DQ catalog covers wave 1 today.

• Trust threshold calibration — thresholds are declared PROVISIONAL.

Documentation

Architecture documentation lives in docs/, written in Portuguese.

PeopleLens AI · LevelInteligencIA · synthetic data, fictional company.