Topics
Topics organize your traffic by what users are asking about — billing disputes, password resets, refund requests — where failure modes organize it by what goes wrong. The Topics page is a taxonomy atlas: topics grouped into spaces, each with volume, failure-rate, and coverage metrics, so you can see which subjects dominate your traffic and which ones your evaluation coverage is missing.
At a glance
| Where it lives | Topics in the sidebar |
| Key API routes | GET /topics/atlas, POST /topics, POST /topics/spaces, PATCH /topics/{id}, POST /topics/{id}/merge, POST /topics/{id}/split |
| What it needs | Nothing — topics involve no LLM calls and no LLM connection |
| Scope | Per agent |
Concepts
- Space — a top-level grouping of topics (e.g. “Support intents”). A topic belongs to one
space and displays a path like
Support intents / Billing dispute. - Topic — a named subject with a severity (
high/medium/low), an owner, a summary, and free-text instructions (e.g. routing guidance for your team). - Assignments — the sessions associated with a topic. Assignments are what the topic metrics and slices are computed from; merging topics moves them.
Each topic carries a source telling you where it came from:
| Source | Meaning |
|---|---|
proposed | Suggested by the Neens starter atlas (see below) |
manual | Created by your team (New topic) |
split | Split off from another topic |
Topics are a curated taxonomy, not a live classifier. The first time an agent touches Topics, Neens seeds a starter atlas: if failure clusters already exist, it proposes one topic per cluster (marked Proposed); otherwise it seeds a generic set of support intents, and spreads a sample of existing sessions across them so the metrics render. From there the atlas is yours to curate — Neens does not currently run a continuous LLM topic classifier over incoming traffic, and no LLM connection is required.
Working with the atlas
The header tiles summarize the filtered atlas: Total topics, Spaces, Proposed (suggestions awaiting curation), and Coverage gaps (topics whose gap score is 0.5 or higher). Filter by space, severity, source, or a name search; click any column header to sort.
- New space / New topic — create a grouping or a topic (name, severity, owner, summary, instructions).
- Click a topic to open its detail panel: metrics, summary, owner, instructions, and up to
five example sessions. From there:
- Curate — edit the topic’s fields (
PATCH /topics/{id}); this is also how you adopt a Proposed topic. - Merge — fold this topic into another: its session assignments move to the target and the source is archived.
- Split — carve a new sub-topic off this one (it lands with source
split, under the parent’s path). - Archive — hide the topic from the atlas without deleting anything.
- Create dataset — start a dataset from the topic’s sessions.
- Curate — edit the topic’s fields (
The metrics
Every topic row computes its metrics live from its assigned sessions:
| Metric | What it is |
|---|---|
| Volume | Number of sessions assigned to the topic |
| Failure rate | Share of those sessions with an error/failed status |
| Coverage gap | 0–1 heuristic that rises with failure rate and falls with volume — high-failure, low-volume topics score highest. A topic with no sessions scores 0.8 (unknown = uncovered). Topics at 0.5+ count in the Coverage gaps tile |
| Share | The topic’s volume as a fraction of the (filtered) atlas total |
Use the coverage gap as a to-do list for your eval program: a topic failing often with little traffic is exactly where a targeted dataset and judge pay off most.
Slicing by topic
Topics are a first-class dimension across Neens:
- Dashboards — the metrics catalogue includes topic measures (Top topics, Topic share), and the topic dimension can slice supported measures in custom dashboard widgets. Note that topic assignments carry no timestamp, so the dashboard time range doesn’t narrow topic-assignment counts.
- Datasets — a dataset can be sourced from a topic (via Create dataset on the topic, or a topic filter on the dataset source), turning a subject area into a reusable evaluation corpus. See Datasets.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The atlas is full of topics you didn’t create | The one-time starter seed proposed them (from your failure clusters, or the generic starter set) | Curate: rename and adopt the useful ones, Merge or Archive the rest |
| A topic’s volume is 0 | No sessions are assigned to it | Merge sessions in from an overlapping topic, or treat it as a coverage gap to instrument |
| Coverage gap seems high everywhere | Low volume per topic dominates the heuristic | Consolidate near-duplicate topics with Merge so volume concentrates |