Customer Grounding

Customer Grounding lets Avelin use an organization’s own knowledge as evidence in workforce decisions.

The Phase 1 capability is available in the public beta through the authenticated Runtime API. It is designed for governed Role Intelligence, not general document chat or automated hiring.

For a new self-service account, successful email verification automatically provisions the finite free beta contract with Customer Grounding enabled. No administrator approval or manual allow-list action is required.

What Problem Does Customer Grounding Solve?

Occupational and labor-market intelligence describe a shared external context. They cannot, by themselves, describe how one organization defines a role, evaluates capability, applies a policy, or conducts an intake.

Customer Grounding adds that organizational reality. A tenant can register and ingest approved sources such as role profiles, competency frameworks, hiring rubrics, policies, and operating guidance. Avelin can then select relevant passages as evidence for a specific grounded decision.

What Customer Grounding Is

Customer Grounding is a governed, account-scoped knowledge layer. It includes the source lifecycle, persisted artifacts, evidence selection, and decision traceability needed to use customer knowledge safely.

It is not:

• a shared cross-customer knowledge base;
• a generic RAG chat interface;
• an external document connector;
• a vector or hybrid retrieval service in the current release;
• an MCP-owned document store;
• an automated hiring system.

Tenant scope is derived from the authenticated Runtime API Key account context. Customer-facing requests and MCP tools do not accept a caller-supplied customer_id.

Evidence

Grounding is the managed body of customer knowledge. Evidence is the selected, traceable material used in one decision.

A grounded Role Intelligence response can include:

• evidence references;
• source and artifact references;
• persisted evidence snapshots;
• confidence factors;
• uncertainty signals;
• review flags;
• a trace identifier.

This distinction matters because uploading a document does not make every statement in it equally relevant to every decision.

Confidence and Review Flags

Confidence indicates how strongly the available evidence supports a conclusion. It is not a guarantee of correctness.

Uncertainty signals identify missing, weak, or conflicting information. Review flags indicate where human attention is recommended. Avelin treats review as part of a governed decision flow, especially when role context is incomplete or customer evidence does not provide enough support.

Decision Traces

A decision trace records the evidence and decision metadata needed to inspect a grounded result. Customer-facing trace projections can include:

• the trace and decision identifiers;
• the access channel;
• evidence, source, and artifact identifiers;
• confidence factors;
• uncertainty signals;
• review flags;
• output sections.

Traces do not expose raw Runtime API Keys, bearer tokens, full prompts, raw documents, local paths, or internal debug payloads.

Typical Workflow

1. Create a Runtime API Key whose contract allows /api/v1/grounding.
2. Inspect GET /api/v1/grounding/capabilities.
3. Register a tenant-scoped source.
4. Ingest approved text, Markdown, or a supported file.
5. Generate a grounded Role Intelligence report.
6. Review evidence references, confidence, uncertainty, and review flags.
7. Retrieve the tenant-scoped decision trace when deeper inspection is needed.
8. Disable, re-enable, or delete the source according to its lifecycle.

The official examples repository contains the complete cURL, Python, file-ingestion, before/after, error, and MCP flows.

Supported Document Types

The current public beta supports:

• direct text/plain and text/markdown ingestion;
• .txt, .text, .md, and .markdown files;
• selectable-text .pdf files;
• .docx files containing paragraphs and straightforward table text.

File uploads are limited to 5 MiB. PDF support does not include OCR or image extraction. DOCX macros and embedded objects are not supported.

Free-Tier Governance

The free beta contract supports two active, unexpired Runtime API Keys. All keys for the contract share:

• 1,000 successful Job, Occupation, and Market calls per UTC day;
• a separate 25 successful Customer Grounding ingestion/report operations per UTC day.

Grounding list/detail/status/usage operations, source registration, enable/disable, and deletion do not consume the 25-operation quota. Only 2xx responses are counted. Rate, payload, and format controls continue to apply to failed or invalid attempts.

An account may retain at most 10 non-deleted Grounding documents and 25 MiB of logical document bytes. Disabled documents still count; deleting a document frees its slot and logical storage. No billing or automatic upgrade is implemented.

If a retained legacy document has no recorded original byte size, new free-tier ingestion fails closed with HTTP 409; the service does not estimate from reduced excerpts. Listing, reading, existing export surfaces, and deletion remain available. Deleting the unknown-size document or completing a separately approved controlled re-ingestion restores calculable capacity.

The current retrieval mode is deterministic persisted-artifact retrieval. External connectors and vector or hybrid retrieval are not part of this release.

Why It Is Different

Customer Grounding does not bypass the Decision Layer. Avelin owns tenant isolation, source lifecycle, evidence selection, confidence, review guidance, and trace semantics.

This keeps customer evidence separate from shared occupational and market intelligence. Applications can review grounded reports alongside job, occupation, or market outputs without treating those sources as interchangeable. The grounded capability behaves consistently whether it is consumed through REST or the customer-operated MCP adapter.

Business Value

Customer Grounding helps organizations move from generic workforce guidance to explainable decisions that reflect their own operating reality.

It can support:

• role calibration against an internal job architecture;
• recruiting intake using a customer hiring rubric;
• competency and skill evidence review;
• policy-aware role guidance;
• trust in AI-assisted workforce workflows;
• audit and review conversations around why a result was produced.

Typical Enterprise Use Cases

Recruiting and role intake

Compare a role request with approved role profiles, competency frameworks, or intake criteria and identify missing information before search begins.

Workforce planning

Use internal role architecture and planning assumptions as evidence when reviewing capability needs or role definitions.

Skills and competency intelligence

Connect detected skill signals with customer-defined competencies while preserving the difference between external reference evidence and internal expectations.

Policy-aware guidance

Bring approved workforce policies or operating guidance into a decision without treating the entire document as an answer.

AI-agent workflows

Allow an MCP-compatible client to call the same grounded Runtime API capability while keeping evidence selection and tenant boundaries inside Avelin.

Controlled-Beta Boundary

The current release does not include external connectors, OCR, vector or hybrid retrieval, SDK wrappers, a full customer UI, billing, or production GA. Grounded Role Intelligence is decision support for human review, not an automated hiring decision.

See the API Overview, MCP, and Examples for integration paths.