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

# Cost Source Discovery

> Understand how Pylva helps builders find, instrument, approve, and price LLM and non-LLM cost sources.

Pylva gives builders a cost coverage workflow. It does not magically infer every external vendor bill.

The SDK auto-captures supported LLM usage. Your app explicitly reports non-LLM usage. `pylva validate` and Data import APIs help teams find, approve, and price sources before they affect margin or billing.

To see which stacks are automatic, callback-based, or manual, see [Supported Integrations](supported-integrations).

## What is a cost source?

A cost source is any provider, tool, or internal service that creates AI-agent cost.

Examples include LLM models, search APIs, speech APIs, vector databases, browser runs, workflow runners, enrichment APIs, and paid internal tools.

## Coverage paths

| Cost type                                    | Recommended path                          | Key             |
| -------------------------------------------- | ----------------------------------------- | --------------- |
| Supported LLM provider call                  | SDK instrumentation or framework callback | Agent SDK key   |
| Non-LLM runtime usage                        | `reportUsage` or `report_usage`           | Agent SDK key   |
| Cost-source declaration from CLI/import jobs | Data import API                           | Data import key |
| Pricing and admin mutations                  | Dashboard or Admin API                    | Admin API key   |

## Discovery workflow

1. Start with SDK telemetry for supported LLM provider calls.
2. Inventory non-LLM services such as search, vector databases, speech, browser runs, workflow runners, enrichment APIs, and internal paid tools.
3. Add `reportUsage` or `report_usage` wherever your app performs non-LLM work that creates cost.
4. Run `pylva validate` to scan the repository for likely cost sources.
5. Use `pylva validate --approve` to declare manual non-LLM sources through the guided CLI flow.
6. Use `pylva validate --ci` to fail CI when a new unapproved source appears.
7. Use `pylva validate --json` when an agent or CI job needs machine-readable output.
8. Review unknown pricing before relying on margin reports, draft invoices, or customer billing.
9. Monitor source health and alert delivery for silent, missing, or broken instrumentation.

## Data import

The Data import API is for trusted CLI or backend jobs that declare cost sources through `POST /api/v1/cost-sources`.

It is not a historical event upload endpoint and it is not a full customer database import API. Use SDK telemetry for runtime events, and use Data import when you need to approve or declare the source and pricing metadata behind those events.

See [Data import: Cost sources](/api/data-import) for the current endpoint.

## Unknown pricing

Pylva can accept usage before pricing is configured. That keeps telemetry flowing, but it also means margin and billing are incomplete until the pricing gap is resolved.

Review unknown pricing before:

* Treating margin reports as final.
* Generating or finalizing customer invoices.
* Activating controls that depend on accurate spend.

## Avoid double counting

Choose one reporting path per source.

* Do not manually report the same model call that SDK instrumentation already captures.
* Do not send the same non-LLM usage through both `reportUsage` and a custom event path.
* Keep metric names and units stable after pricing them.
* Use opaque `customer_id` values and stable `step` names so cost coverage maps to customer and workflow reports.

If a source is important enough to affect margin, it should have an explicit owner, metric, unit, pricing rule, and dashboard review path.