Skip to main content
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.

​
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 typeRecommended pathKey
Supported LLM provider callSDK instrumentation or framework callbackAgent SDK key
Non-LLM runtime usagereportUsage or report_usageAgent SDK key
Cost-source declaration from CLI/import jobsData import APIData import key
Pricing and admin mutationsDashboard or Admin APIAdmin 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 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.