> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Concepts
> Every key concept in DecimalAI — how traces, manifests, evaluations, and multi-agent systems work together.
DecimalAI is built around a single idea: **when your agent changes, you need to know what still holds.** Every trace your agent produces is tied to the exact agent configuration that produced it — its **manifest**. When you change a prompt, swap a model, add a tool, or edit a sub-agent, DecimalAI knows precisely which past traces are still valid and which are now stale. This is **manifest-aware versioning**, and it is the foundation under everything else.
This page is the entry point — each section below has its own focused deep-dive.
## The foundation: manifest-aware versioning
A **manifest** is a structured snapshot of your agent across ten compatibility surfaces — prompt stack, model runtime, tool registry, skill registry, workflow, sub-agents, output contract, guardrails, context config, and environment. Every trace records the manifest it ran under. When the manifest changes, DecimalAI compares old to new surface-by-surface and tells you, for each past trace, whether it was structurally touched.
That single capability is what makes the three product capabilities possible:
| Capability | What it answers | What manifest-awareness gives it |
| ---------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Regression checks** | Did this change break anything? | Knows exactly which surfaces changed, so it scopes the check to traces that actually depend on them |
| **Skills registry** | Which skills measurably help? | A skill is a manifest surface; SkillScore is measured against the manifest the trace ran under |
| **Training-data validation** | Which traces are safe to train on? | Stale traces — those whose manifest no longer matches the current agent — are filtered before they poison a dataset |
Each capability works on its own. They compound because they share one model of what an agent *is* — its manifest.
## The agent lifecycle
Manifest-aware versioning tracks your agent across its whole life — from the first prototype to a retrained model that starts the cycle again.
```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
flowchart LR
A[Prototype] --> B[Ship] --> C[Improve] --> D[Retrain] --> B
```
| Stage | What happens | What manifest-awareness does |
| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
| **Prototype** | You build the agent and capture first traces | Records the initial manifest as the baseline |
| **Ship** | The agent runs in production | Stamps every trace with the manifest it ran under |
| **Improve** | You change a prompt, model, tool, or sub-agent | Runs a regression check; flags which past traces are now stale |
| **Retrain** | Valid traces become a training set; you fine-tune | Filters out stale traces, then a better model ships and the loop repeats |
The three capabilities each work standalone, but they compound on one foundation — manifest-aware versioning.
## The data model
These are the core entities DecimalAI captures and how they relate. A **session** groups the traces of one logical run; each **trace** is pinned to the **manifest** it executed under and decomposes into **spans** and **LLM calls**; a trace can link to a parent trace when a sub-agent is invoked.
```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
erDiagram
SESSION ||--o{ TRACE : groups
MANIFEST ||--o{ TRACE : "pins (each trace runs under one)"
TRACE ||--o{ SPAN : "decomposes into"
TRACE ||--o{ LLM_CALL : "records"
TRACE ||--o{ TRACE : "parent_trace_id (sub-agent)"
```
| Entity | What it is |
| --------------------- | ---------------------------------------------------------------------------- |
| **Session** | A logical run that groups one or more traces |
| **Trace** | One agent execution, pinned to the manifest that produced it |
| **Manifest** | The structured snapshot of the agent across its ten compatibility surfaces |
| **Span** | A single step inside a trace (a tool call, a retrieval, a sub-step) |
| **LLM Call** | A single model invocation recorded within a trace |
| **parent\_trace\_id** | Self-link on Trace — set when a sub-agent trace is spawned by a parent trace |
## Read in order
Traces, spans, LLM calls, sessions — how DecimalAI captures and organizes agent activity.
Manifests, components, compatibility verdicts, repair — the core innovation.
Evaluators, eval scores, eval verdicts, the unified decision engine.
Orchestrators, sub-agents, delegation vs handoff, drift detection.
Skills (SKILL.md), datasets, export formats (SFT/DPO), replay, repair.
Quick A-Z reference for any term.
## The improvement loop
Putting all the concepts together, here's how they connect into a continuous cycle:
```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
flowchart TD
A[Agent runs] --> B[Traces captured]
B --> C{Manifest change
detected?}
C -->|yes| D[Compatibility report
drop incompatible traces]
C -->|no| E[Evaluators score traces]
D --> E
E --> F{Eval verdict}
F -->|pass| G[Keep for training]
F -->|fail| H[Replay with new agent]
H --> G
G --> I[Build dataset
keep + pass only]
I --> J[Fine-tune model]
J -->|better model produces
better traces| A
```
This loop runs continuously. Each iteration produces a better model, which produces better traces, which produce better training data.
## Where to next
If you're new — install the SDK and get your first trace in 5 minutes.
One command seeds a demo agent and links you to a live impact report.
A-Z quick reference for any term used in these concept pages.
Every REST endpoint with examples and schemas.