HERC: your AI assistant and home page¶

HERC is the home page of Datahub and the doorway to everything else. It greets you with what's trending and pending, then steps in as a conversational AI assistant who can answer questions, summarise content, and (on request) act on your behalf across the platform.

It exists so you don't have to learn the platform's information architecture before getting value from it. If you can describe what you want, HERC can usually take you there — or do it for you.

When to choose this¶

Use HERC when you want to:

Find something fast. "Show me the Customer Lifetime Value metric." → HERC links you straight to it.
Ask a business question. "What was revenue last month?" → HERC routes through the metric agent and answers with the number.
Summarise a body of work. "What changed in the Finance domain this week?" → HERC reads activity logs and gives a digest.
Get suggestions. "Suggest five metrics I could build for the new Subscriptions contract." → HERC analyses the contract's tables and proposes them.
Handle a vague request. "Where do I configure provider keys?" → HERC navigates you there.
Hand off to a specialist agent. A complex catalog or glossary question is routed to the right module agent automatically.

You do not need HERC for:

Bulk operations (use the module's import / export).
Privileged admin actions HERC doesn't have access to (HERC respects your roles).
Free-form data analysis on raw warehouse tables (HERC works through governed metrics; for ad-hoc, use a notebook or Insights).

What HERC looks like¶

Surface	Where	What you see
Home page	`/`	Greeting, trending entities (top assets / metrics / terms by recent activity), recent activity feed, pending tasks count, the chat input.
Chat panel	Bottom-right of every page	Click the orange spark icon → side panel opens with conversational chat. Persistent across pages.
Conversation history	Chat panel → history icon	Past conversations, restorable.
Suggestions row	Below the chat input	One-click prompts contextual to where you are (e.g. on a metric detail: Explain this metric, Show similar metrics).

How HERC works¶

HERC is a routed agent system. When you send a message:

Fast routing. A keyword router (FastRouter) inspects the message in English and Dutch. If it strongly matches a module's keywords (e.g. "metric", "kpi", "dashboard", "glossary term") it routes directly to that module's agent.
LLM fallback. Otherwise the message goes to the orchestrator agent, which reads the platform's context (your role, the page you're on, recent activity) and decides which agent or tool to call.
Specialist agent. A module agent (e.g. metricmodule agent, businessglossary agent, datacatalog agent) executes — it has access to the module's MCP tools (search assets, get metric, define a draft, …).
Streamed reply. Tokens stream into the chat panel. Tool calls are surfaced as inline status messages ("Searching the glossary…").
Follow-ups. After a reply, HERC suggests two or three follow-up questions you can click to continue.

Every call is scoped to your JWT — HERC cannot see, modify, or surface anything you don't have a role to see.

Agentic loop — plan, act, confirm¶

For multi-step tasks (e.g. "create three metrics for the Subscriptions contract"), HERC now shows its work before and during execution.

What you see¶

When HERC's reply involves two or more meaningful steps, it opens a collapsible activity strip above the response:

Plan steps (e.g. "1. Look up the contract's tables · 2. Draft each metric · 3. Save them") — shown as a numbered checklist. Each step updates as HERC works: pending → in progress → done.
Tool calls — inline chips showing what action HERC just ran and why ("Looking up Subscriptions contract").
Mid-turn revisions — if HERC discovers something unexpected (a table name has changed), it updates the plan and adds a note. Revisions are capped at two per turn.
Completion summary — once the turn completes, the strip collapses to a one-liner: "3/3 steps · 4 tools · 6 s".

For simple one-tool questions (e.g. "what's the definition of churn?") the strip does not appear.

Asking for your input¶

If HERC reaches a genuine fork — for example it found two tables that could both be the right source and neither is obviously correct — it pauses and shows a clarifying question with optional quick-reply chips:

"Which table should I use as the base for the Active Customers metric — customers_raw or customers_deduplicated?"
[customers_raw] [customers_deduplicated] [Show me both]

Tap a chip or type your own answer. HERC resumes from exactly where it paused — no need to repeat yourself.

Scroll-back¶

Plans persist with the assistant message. If you scroll back through a conversation you can see what HERC planned and which steps it took, in order.

When HERC pauses vs presses on¶

Situation	What HERC does
Discovers a minor schema difference	Updates the plan silently, continues
Encounters a clear ambiguity tools cannot resolve	Pauses and asks you
Hits a tool error it can recover from	Marks the step failed, revises, retries
Hits a permissions error	Stops and explains what role is needed

What's on the home page¶

The home page is HERC's "what's happening" dashboard:

Trending entities. Top entities by activity count over a configurable window (last 7 / 30 days). Calculated by aggregating audit-log events across catalog assets, glossary terms, metrics, contracts, products, processes, alert rules, and flows. Click any row to jump to the entity.
Recent activity. Stream of platform events: assets updated, terms approved, contracts published, alert rules triggered. Tells you what your colleagues have been doing.
Pending tasks. Count of open inbox tasks (the actual list lives in Tasks).
Quickstart panel. For new tenants: step-by-step on-ramps to each module ("Connect your warehouse", "Define your first metric", "Build a process").

Setup — what an admin needs to do once¶

Prereq	Where	Why
AI provider key	`/admin/integrations` → AI Provider Keys (or `/ai/provider-keys`)	Required for all conversational AI. Without it HERC can answer simple navigation questions but can't reason.
Roles	`/rolegroups`	`herc.read` is included in every authenticated role group by default — every user sees HERC.
Brain index built	`/dna`	The first time a tenant logs in HERC's answers improve dramatically once the Organisation DNA graph has been built.
(Optional) Private AI	License + `/admin/integrations`	Tenants on the Private AI license can run HERC on the platform's hosted model — see the AI platform page.

Examples worth trying¶

You ask	What happens
"How many active customers do we have?"	Routed to the metric agent → searches metrics → finds Active Customers → executes the metric → returns the number with a link to the metric.
"What's the definition of churn?"	Routed to the glossary agent → returns the Churn term's definition with a link.
"Find me PII tables in the warehouse."	Routed to the catalog agent → semantic search across tagged assets → returns top matches.
"Summarise the changes to the Finance domain this week."	Orchestrator → reads audit logs filtered by domain tag → returns a bulleted digest.
"Set up a new metric for Net Revenue."	Orchestrator → metric agent proposes a draft (table, measure, time grain) → you accept/edit.
"What's broken right now?"	Routed to alert agent → returns currently-firing alert rules.

Limitations¶

Limit	Why	Workaround
HERC can't run SQL you write directly.	The platform routes through governed metrics and catalog assets.	Use Insights for ad-hoc; HERC will help you build the card.
HERC respects your roles strictly.	A user without `metric.read` cannot ask HERC for a metric value.	Have an admin grant the role.
Some tools are advisory (suggestions), not mutating.	Safety. HERC suggests; you approve.	Accept the suggestion to apply it.
Long conversations may go stale.	Provider context limits.	Start a new conversation when switching topics.
Brand-new tenants get thin answers.	DNA graph hasn't been built yet.	Build the brain index from `/dna`.
HERC can't see audio or images.	Text-in / text-out.	For meeting notes, use Transcription and ask HERC about the transcript.

Audit & compliance¶

Question a CISO might ask	Where to look
"Who asked HERC what?"	All conversations are stored per-user; admins can audit via `/ai/observability` (Arize Phoenix).
"Did HERC see data this user shouldn't?"	Tool calls are scoped to the user's JWT; the same role checks that gate the UI gate the agent.
"Where do queries physically go?"	Whichever AI provider is configured under `/admin/integrations`. With Private AI, queries stay on the platform.
"Can HERC make irreversible changes?"	Mutating tools require explicit confirmation in the UI. HERC proposes; you click apply.
"Are conversations retained?"	Yes, per-user, configurable retention. Archive any conversation from the history panel.

Troubleshooting¶

Symptom	Likely cause	Fix
HERC says "I don't have a provider configured"	No AI provider key.	`/admin/integrations` → AI Provider Keys → add one.
Answers feel generic / wrong	Brain index hasn't been built or is stale.	`/dna` → re-index.
HERC can't find a metric you know exists	The metric is archived or you don't have `metric.read`.	Check archive state; verify your roles.
Trending list is empty	Tenant is new — no activity yet.	Use the platform for a few days; trending populates from audit logs.
Chat panel stuck on "Thinking…"	Provider rate-limit or network blip.	Cancel and retry; check `/ai/observability` for the trace.
Follow-up suggestions are missing	The agent that answered doesn't have follow-ups configured for that tool.	Cosmetic; doesn't affect the answer.