> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Concepts

> Core concepts behind Nexio's agentic infrastructure.

## Engines

An **engine** is a configured instance of a Nexio pattern. Each engine has an `engine_type` that determines its behavior:

| Engine type       | What it does                                                                |
| ----------------- | --------------------------------------------------------------------------- |
| `placement`       | Ranks offerings from multiple providers into optimal solutions              |
| `entity_analysis` | Analyzes current state against requirements, finds gaps and recommendations |

More engine types are planned. See the [Headless Engine Setup](/guides/headless-engine-setup) guide for creating and configuring engines via API.

## Runs

A **run** is an async job submitted to `POST /api/v1/engines/{engine_slug}/runs`. Each run gets a `run_id` and is
processed through the engine's pipeline. Poll `GET /api/v1/runs/{run_id}` for results.

## Input

`input` is the subject's profile and run context. What goes in `input` depends on your engine's configuration and domain.

<Note>
  Field names like `coverage_types` and `premium` reflect the current API contract. Your engine's configuration determines which input fields are relevant. Open the per-engine **Contract page** on platform.usenexio.com (Copy-for-agents button) to see the exact typed request schema for your engine.
</Note>

## Offerings

`offerings` is the array of provider offerings Nexio evaluates in a placement engine. Each offering represents one provider's
entry for one requirement category. If you have 3 providers each offering 3 categories, that's 9 offerings.

## Solutions

Nexio assembles offerings into ranked **solutions**: complete packages that satisfy the stated
requirements. Solutions may combine offerings from a single provider or mix providers, whichever
combinations score best.

Each solution has a `rank` (1 = best) and a `cluster_label` that categorizes it:
`recommended`, `best_value`, `best_coverage`, or `simplest`.

## Engine Types

The engine you call determines the contract and the pipeline that runs.

| Engine type       | Typical payload                             | Typical result                          |
| ----------------- | ------------------------------------------- | --------------------------------------- |
| `placement`       | `input` plus top-level `offerings`          | Ranked `solutions` with scorecards      |
| `entity_analysis` | `input` only, shaped by the engine contract | Requirements, gaps, and profile summary |

Open the per-engine **Contract** page on
[platform.usenexio.com](https://platform.usenexio.com) (Copy-for-agents button) when you need the
exact field-level typed schema for a specific engine.

## Solutions (detail)

A **solution** is a ranked package. Each includes:

* `offerings`: the selected items in the package
* `provider_count`: 1 = single provider, 2+ = mixed
* `est_cost_low` / `est_cost_high`: annual cost range
* `scorecard`: multi-dimension evaluation
* `rank` and `cluster_label`

Provider identity is on `solutions[*].offerings[*].provider_name`, not on the solution root.

## Ranking strategy

`appetite_bucket` controls how Nexio weights the scorecard dimensions when ranking solutions.
Set it in `input` to express the priority:

| `appetite_bucket` | Emphasis                               |
| ----------------- | -------------------------------------- |
| `coverage_first`  | Broadest coverage, strongest offerings |
| `cost_sensitive`  | Lowest cost within quality bounds      |
| `simplicity`      | Fewest providers, easiest to accept    |
| `balanced`        | Even weighting across all dimensions   |

When omitted, Nexio infers it from submission signals.

The top-ranked solution's label is returned in `output.top_label` and on each solution as
`cluster_label`. Labels like `recommended`, `best_value`, `best_coverage`, and `simplest`
reflect where each solution excels: they're the output side of the ranking strategy.

## Scorecards

Six dimensions, each rated L1–L4 (lower is better):

* `coverage_completeness`: how completely the solution addresses requirements
* `pricing_competitiveness`: cost relative to alternatives and budget
* `provider_quality`: provider ratings and reputation
* `placement_likelihood`: likelihood of successful acceptance
* `operational_simplicity`: number of providers, complexity of execution
* `risk_alignment`: fit between provider specialties and the subject's profile

The package score is `scorecard.overall_level`, a raw weighted level based on
the ranking strategy. Use the emitted solution `rank`, not the raw weighted
level, as the ordering contract.

<Note>
  Dimension names like `coverage_completeness` reflect the default engine configuration. Custom engines can define their own scoring dimensions via the [Update Config](/api-reference/engines/update-engine-config) endpoint.
</Note>

## The pipeline

### Placement

| Stage    | What happens                                                             |
| -------- | ------------------------------------------------------------------------ |
| INTAKE   | Parse submission, infer requirements                                     |
| FILTER   | Remove offerings that fail hard constraints (region, category, capacity) |
| MATCH    | Match remaining offerings to requirements by category                    |
| ASSEMBLE | Build candidate solutions with bundle discounts                          |
| EVALUATE | Score across dimensions, rank, and label                                 |

### Entity analysis

| Step                 | What happens                                          |
| -------------------- | ----------------------------------------------------- |
| Infer Requirements   | Generate needs from the subject's profile and context |
| Punch Card Check     | Compare against current portfolio (MET / UNMET)       |
| Deterministic Checks | Rule-based gap detection                              |
| LLM Adequacy         | AI analysis of adequacy                               |
| Merge & Dedupe       | Combine gaps, sort by severity (HIGH → MEDIUM → LOW)  |

Returns gaps with severity, recommendations, profile summary, and flags. See the
[Get Run Status](/api-reference/engines/get-run-status) response schema for full field details.

## Output fields you may see

These fields appear on `output` and on individual gap entries depending on engine
configuration. Integrators should treat them as additive: absent on engines that
don't enable them, present when the engine does.

### `output.degradation_reason`

Populated on `degraded` runs (and on placement runs that completed cleanly with
no usable output). One of:

| Value                 | Meaning                                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `no_requirements`     | No coverage requirements parsed from input (placement)                                                |
| `no_offerings`        | Every offering filtered out before scoring (placement)                                                |
| `no_combinations`     | No candidate placement combinations (placement)                                                       |
| `input_quality`       | Customer-fixable input warning (`MALFORMED_FIELD`, `MISSING_FIELD`, `OUT_OF_RANGE`, `FIELD_CONFLICT`) |
| `llm_degraded`        | LLM provider failure                                                                                  |
| `enrichment_degraded` | Enrichment upstream outage                                                                            |
| `scoring_rule_failed` | Engine-side scoring rule violation                                                                    |
| `mixed`               | Reserved for future use; not currently emitted                                                        |
| `other`               | Non-info diagnostic that doesn't match a known family (catchall)                                      |

Omitted on healthy completions. Route on this field instead of parsing free-text
from `output.diagnostic` or walking `warning_details[]`. When multiple non-info
diagnostics are present, strict precedence picks the most actionable single
reason: `scoring_rule_failed` > `input_quality` > `llm_degraded` >
`enrichment_degraded` > `other`.

### `data_source_labels` (entity analysis)

Per-gap sibling to `data_sources[]`. Index-aligned broker-readable labels for
each entry in `data_sources`. `data_sources` keeps its audit-trail role (raw
input paths); `data_source_labels` adds a display string per path so broker UIs
can render evidence captions without maintaining their own mapping. Unmatched
paths emit empty strings at the corresponding index: fall back to the raw
path. Omitted when the engine has no `data_source_labels` map configured.

## Rate limits

Rate limits are enforced on the public API. `429 Too Many Requests` includes a `Retry-After` header.
Contact [support@usenexio.com](mailto:support@usenexio.com) for higher limits.