v2.0.1

Governance Insights

This tutorial demonstrates Phase 3 governance insight tools: experiment summaries, candidate explanations, comparative insights, investigations by correlation/job/audit, drift explanations, and report generation.

Overview

Phase 3 governance insight tools are read-only. They summarize existing experiment, audit, job, evaluation, and drift evidence. They do not promote, deploy, approve releases, or mutate governance state.

Experiment insights

Get a summary of an experiment's evidence:

bash

curl http://localhost:8000/api/v1/experiments/experiment-1/insights

Candidate explanation

Explain why a specific candidate scored as it did:

bash

curl http://localhost:8000/api/v1/experiments/experiment-1/candidates/candidate-a/insights

Comparative insights

Compare candidates across multiple dimensions:

bash

curl http://localhost:8000/api/v1/experiments/experiment-1/comparative-insights

Investigations

Investigate by correlation ID, job ID, or audit record:

bash

# By correlation ID
curl http://localhost:8000/api/v1/investigations/by-correlation/corr-1

# By job ID
curl http://localhost:8000/api/v1/investigations/by-job/job-1

# By audit record
curl http://localhost:8000/api/v1/investigations/by-audit/audit-1

Drift explanation

Get a human-readable explanation of drift between evaluations:

bash

# Drift explanation by drift ID
curl http://localhost:8000/api/v1/governance/drift/eval-a..eval-b/explanation

# Evaluation drift explanation
curl http://localhost:8000/api/v1/evaluations/eval-b/drift-explanation

Report generation

Generate governance evidence reports as JSON or Markdown:

bash

# Experiment report (JSON)
curl "http://localhost:8000/api/v1/reports/experiments/experiment-1?format=json"

# Experiment report (Markdown)
curl "http://localhost:8000/api/v1/reports/experiments/experiment-1?format=markdown"

# Investigation report
curl http://localhost:8000/api/v1/reports/investigations/corr-1

# MCP audit report
curl http://localhost:8000/api/v1/reports/mcp-audit/audit-1

MCP equivalents

All insight endpoints are also available as MCP tools. For example:

python

from kavach import create_mcp_server

server = create_mcp_server()

# Summarize an experiment
result = server.call_tool(
    "governance.summarize_experiment",
    {"experiment_id": "experiment-1"}
)

# Explain a candidate
result = server.call_tool(
    "governance.explain_candidate",
    {"experiment_id": "experiment-1", "candidate_id": "candidate-a"}
)

# Generate experiment report (JSON)
result = server.call_tool(
    "governance.generate_experiment_report",
    {"experiment_id": "experiment-1", "format": "json"}
)