Skip to content

Analytics Agent

The Analytics Agent turns a natural-language question into a proposed SQL artifact. Themis can execute and check that artifact.

The agent is not the release authority.

Public route

The public Themis demo is available at Analytics Agent.

The public instance is deliberately limited:

  • one Themis engine: themis_nyc_taxi;
  • read-only SQL;
  • Themis release-evidence questions;
  • read-only Themis receipt and Jaeger evidence through an internal MCP bridge;
  • DataHub grounding when the signal is available;
  • no Apollo engine or Apollo catalog;
  • no settings, connector installation, OAuth, release administration, or conversation-history enumeration.

The shared Apollo Analytics Agent stays on its own private loopback port. The public route does not select or proxy that engine.

Good questions

Use questions that connect analytics to release evidence.

  • “Return the NYC taxi row count. Show the read-only SQL and explain how Themis independently checks it.”
  • “Audit schema, lineage, ownership, quality, and lifecycle evidence for nyc_taxi. List every signal that is missing.”
  • “Design a replay case that catches use of the deprecated congestion_surcharge field.”
  • “Explain the path from agent SQL to DuckDB replay, independent oracle, DataHub evidence, and the final receipt.”
  • “Use live Themis evidence to explain how trace IDs and parent span IDs correlate across replay, oracle, evaluation, and receipt write-back.”

OpenTelemetry questions

The public agent has a narrow, read-only evidence bridge. It can query only configured demonstration receipt IDs and Jaeger traces referenced by those validated receipts. It cannot browse arbitrary release history, query an arbitrary trace ID, or access the Themis mutation API.

It must not invent answers to questions such as:

  • “What is the latest release trace ID?”
  • “How many spans did this release create?”
  • “What was the duration of this span?”

If the bridge reports that a value is unavailable, label it UNVERIFIED and use the Themis workspace for the visitor’s current run. A configured demonstration receipt is evidence from that receipt, not a claim about the visitor’s current release.

For every factual answer, label claims OBSERVED, DERIVED, HISTORICAL, PROPOSED, or UNVERIFIED. The agent must not issue a current PROMOTE, REVIEW, or QUARANTINE decision.

Agent to gate boundary

The flow is:

Step Owner Result
Understand the question Analytics Agent Proposed SQL and tool evidence
Check the artifact Themis Read-only and digest validation
Run the query Themis Result on the frozen snapshot
Check expected behavior Themis Independent oracle comparison
Check meaning and governance DataHub through Themis Metadata evidence
Decide Themis policy PROMOTE, REVIEW, or QUARANTINE

The agent can help with step one. It cannot skip the other steps.

Provider keys

Keep provider keys in a private environment file or secret manager. Do not place a key in a manifest, URL, browser bundle, receipt, or public documentation.