What Is ML Diagnostics?

What Is ML Diagnostics?

ML diagnostics is the debug layer of an ML system. Where monitoring tells you that a metric moved, diagnostics tells you which model version, prompt template, retrieved chunk, tool call, or user cohort is responsible. In 2026-era LLM and agent stacks, diagnostics combines traceAI spans, per-cohort evaluator scores, dataset slicing, and replay against a frozen golden set. The output is not a graph: it is a localized defect that an engineer can fix, like “prompt-v17 regresses Groundedness by 12% on the refund-agent route after a retriever change.” FutureAGI surfaces those signals in one timeline.

Why It Matters in Production LLM/Agent Systems

Without diagnostics, every regression turns into a multi-hour scavenger hunt. A user reports a wrong answer. The dashboard shows latency is fine and error rate is normal. Engineers grep logs, replay prompts in a playground, and guess. Two failure modes dominate: false-clean dashboards (aggregate metrics hide a bad cohort) and tangled blame (model, prompt, retriever, and tool change in the same week).

The pain crosses teams. On-call SREs see a p99 spike with no obvious offending span. ML engineers cannot reproduce a hallucination because the production trace was not stored with its retrieved context. Product managers cannot tell a customer which fix shipped and when. Compliance teams cannot answer a regulator who asks why a specific output happened on a specific date.

Agentic pipelines make this worse. One user query may trigger a planner call, three tool calls, two retrievals, and a summarizer. A regression at the planner step propagates downstream and looks like a summarizer bug. Without span-level diagnostics, the team fixes the wrong layer. With them, the failing span carries its own evaluator scores, prompt version, and inputs — and the fix is one PR.

How FutureAGI handles ML diagnostics

The specified FutureAGI anchor for this term is sdk:Dataset plus traceAI:*. FutureAGI’s approach is to make every regression debuggable from one of three entry points: a failing trace, a failing eval row, or a failing cohort.

A real workflow starts when production TaskCompletion drops 6% on the support-agent route. Engineers open the FutureAGI tracing view, filter by route=support-agent and eval.task_completion < 0.7, and pull the offending traces from the last 24 hours. Each trace already carries traceAI attributes — llm.model, prompt.version, agent.trajectory.step, retrieval.chunk_ids, gen_ai.server.time_to_first_token — emitted by traceAI-langchain or traceAI-openai. The team slices by prompt version and finds 89% of failures hit prompt-v17.

The team then exports the failing rows into a Dataset, runs Dataset.add_evaluation with Groundedness, ChunkAttribution, and ContextRelevance, and confirms that ChunkAttribution is the breaking metric — the model is ignoring the retrieved chunk. The fix is a prompt change, validated by re-running evaluators on the same dataset slice. Unlike a generic LangSmith trace view that shows spans without attached evaluator results, FutureAGI keeps span, prompt version, eval score, and dataset row in one record so the diagnostic loop closes in minutes, not hours.

How to Measure or Detect It

Treat ML diagnostics as a measurable capability:

• Time-to-root-cause (TTRC): median minutes from alert to identified defect; the canonical diagnostic KPI.
• Trace coverage: percentage of production calls instrumented with traceAI; gaps create blind spots.
• Cohort granularity: how narrowly you can slice (route, prompt version, model, user tier, region); narrower is better.
• Evaluator-on-trace ratio: fraction of production traces that have at least one evaluator score attached for replay.
• Replay reproducibility: percentage of failing traces that reproduce when re-run against the stored prompt and context.
• Cohort eval drift: per-cohort Groundedness or TaskCompletion deltas across a 7-day window highlight slow regressions.

Slice-and-eval pattern for diagnosis:

from fi.evals import ChunkAttribution

bad_rows = dataset.filter(prompt_version="v17")
result = ChunkAttribution().evaluate(
    response=bad_rows["response"],
    context=bad_rows["context"],
)

Common Mistakes

• Looking only at aggregate dashboards: a 1% global drop can be a 25% drop on one cohort; aggregates hide diagnostics.
• Storing traces without evaluator scores: replay tells you what happened but not whether it was wrong.
• Mixing changes: shipping a prompt, model, and retriever update together makes diagnosis impossible — gate them separately.
• Ignoring tool spans: in agents, the failing span is often a tool call, not the LLM completion.
• Treating every regression as a model bug: prompt, retriever, schema, and gateway routing changes are equally common root causes.