# Authentication Source: https://docs.valmi.io/docs/api-reference/authentication How to authenticate API requests All API requests require authentication using an API key. ## API Keys API keys are created in the Control Plane under **Settings** → **API Keys**. ## Authentication Header Include your API key in the `Authorization` header: ```bash theme={null} Authorization: Bearer sk_api_abc123xyz ``` ## Example Request ```bash theme={null} curl -X GET https://api.valmi.io/v1/agents \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" ``` ## API Key Types ### SDK Keys Used by SDKs to send metering events: * Format: `sk_live_...` or `sk_test_...` * Permissions: Send actions, send outcomes, read usage ### API Keys Used for direct API access: * Format: `sk_api_...` * Permissions: Configurable (read-only, read-write, admin) ## Base URL All API requests go to: ``` https://api.valmi.io/v1 ``` ## Rate Limiting API requests are rate-limited: * **SDK Keys**: 10,000 requests per minute * **API Keys**: 1,000 requests per minute Rate limit headers are included in responses: * `X-RateLimit-Limit`: Request limit * `X-RateLimit-Remaining`: Remaining requests * `X-RateLimit-Reset`: When limit resets ## Error Responses Invalid authentication returns `401 Unauthorized`: ```json theme={null} { "error": { "code": "unauthorized", "message": "Invalid API key" } } ``` # Accounts Source: https://docs.valmi.io/docs/api-reference/endpoints/accounts Manage customer accounts ## List Accounts /v1/accounts List all accounts. List of accounts ```bash theme={null} curl -X GET https://api.valmi.io/v1/accounts \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ## Create Account /v1/accounts Create a new account. ### Body Account name Billing email Billing address ```bash theme={null} curl -X POST https://api.valmi.io/v1/accounts \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corp", "email": "billing@acme.com", "billing_address": { "street": "123 Main St", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US" } }' ``` # Agents Source: https://docs.valmi.io/docs/api-reference/endpoints/agents Manage agents and agent instances ## List Agents /v1/agents List all agents. ### Query Parameters Maximum number of agents to return (default: 20, max: 100) Number of agents to skip (default: 0) List of agents Total number of agents ```bash theme={null} curl -X GET https://api.valmi.io/v1/agents \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ```json theme={null} { "agents": [ { "id": "agent_abc123", "name": "Customer Support Bot", "type": "langgraph", "created_at": "2024-01-15T10:00:00Z" } ], "total": 1 } ``` ## Get Agent /v1/agents/ Get details of a specific agent. Agent ID Agent name Agent type (langgraph, crewai, n8n, custom) ```bash theme={null} curl -X GET https://api.valmi.io/v1/agents/agent_abc123 \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ## Create Agent /v1/agents Create a new agent. ### Body Agent name Agent type (langgraph, crewai, n8n, custom) Agent description ```bash theme={null} curl -X POST https://api.valmi.io/v1/agents \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Support Bot", "type": "langgraph", "description": "AI customer support agent" }' ``` # Costs Source: https://docs.valmi.io/docs/api-reference/endpoints/costs Query and manage cost allocation ## Get Costs /v1/costs Query costs with filters. ### Query Parameters Filter by agent ID Filter by customer ID Start date (ISO 8601) End date (ISO 8601) List of costs Total cost amount ```bash theme={null} curl -X GET "https://api.valmi.io/v1/costs?agent_id=agent_abc123&start_date=2024-01-01&end_date=2024-01-31" \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ```json theme={null} { "costs": [ { "id": "cost_xyz789", "agent_id": "agent_abc123", "cost_type": "llm", "amount": 100.50, "currency": "USD", "period": "2024-01" } ], "total": 100.50 } ``` # Invoices Source: https://docs.valmi.io/docs/api-reference/endpoints/invoices Manage invoices and billing ## List Invoices /v1/invoices List all invoices. List of invoices ```bash theme={null} curl -X GET https://api.valmi.io/v1/invoices \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ## Generate Invoice /v1/invoices/generate Generate invoices for a billing period. ### Body Account ID (optional, generates for all if not provided) Billing period (YYYY-MM) ```bash theme={null} curl -X POST https://api.valmi.io/v1/invoices/generate \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "billing_period": "2024-01" }' ``` # Metering Events Source: https://docs.valmi.io/docs/api-reference/endpoints/metering-events Send actions and outcomes via API ## Send Action /v1/actions Send an action event. ### Body Agent instance key Action type (llm\_call, tool\_call, etc.) Action metadata (key-value pairs) Event timestamp (ISO 8601, defaults to now) ```bash theme={null} curl -X POST https://api.valmi.io/v1/actions \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "agent_key": "agent_abc123xyz", "action_type": "llm_call", "metadata": { "model": "gpt-4", "input_tokens": 1000, "output_tokens": 500 } }' ``` ```json theme={null} { "id": "action_xyz789", "status": "processed", "created_at": "2024-01-15T10:30:00Z" } ``` ## Send Outcome /v1/outcomes Send an outcome event. ### Body Agent instance key Outcome type (successful\_hire, converted\_lead, etc.) Outcome value (count or amount) Outcome metadata ```bash theme={null} curl -X POST https://api.valmi.io/v1/outcomes \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "agent_key": "agent_abc123xyz", "outcome_type": "successful_hire", "value": 1, "metadata": { "candidate_id": "cand_123" } }' ``` # Pricing Source: https://docs.valmi.io/docs/api-reference/endpoints/pricing Query pricing and rate plans ## List Rate Plans /v1/pricing/rate-plans List all rate plans. List of rate plans ```bash theme={null} curl -X GET https://api.valmi.io/v1/pricing/rate-plans \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ## Get Rate Plan /v1/pricing/rate-plans/ Get details of a specific rate plan. ```bash theme={null} curl -X GET https://api.valmi.io/v1/pricing/rate-plans/plan_abc123 \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ## Simulate Pricing /v1/pricing/simulate Simulate pricing for sample usage. ### Body Rate plan ID Sample usage data Calculated charges Total charge amount ```bash theme={null} curl -X POST https://api.valmi.io/v1/pricing/simulate \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "rate_plan_id": "plan_abc123", "usage": { "tokens": 50000, "api_calls": 1000 } }' ``` # Reporting Source: https://docs.valmi.io/docs/api-reference/endpoints/reporting Revenue analytics and PnL reporting ## Get Revenue Report /v1/reports/revenue Get revenue report with breakdown. ### Query Parameters Start date (ISO 8601) End date (ISO 8601) Group by (agent, customer, product) Total revenue Revenue breakdown ```bash theme={null} curl -X GET "https://api.valmi.io/v1/reports/revenue?start_date=2024-01-01&end_date=2024-01-31&group_by=agent" \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ## Get PnL Report /v1/reports/pnl Get profit and loss report. ### Query Parameters Start date (ISO 8601) End date (ISO 8601) Total revenue Total costs Margin (revenue - costs) Margin percentage ```bash theme={null} curl -X GET "https://api.valmi.io/v1/reports/pnl?start_date=2024-01-01&end_date=2024-01-31" \ -H "Authorization: Bearer sk_api_abc123xyz" ``` # Subscriptions Source: https://docs.valmi.io/docs/api-reference/endpoints/subscriptions Manage customer subscriptions ## List Subscriptions /v1/subscriptions List all subscriptions. List of subscriptions ```bash theme={null} curl -X GET https://api.valmi.io/v1/subscriptions \ -H "Authorization: Bearer sk_api_abc123xyz" ``` ## Create Subscription /v1/subscriptions Create a new subscription. ### Body Account ID Rate plan ID Agent instance IDs to include ```bash theme={null} curl -X POST https://api.valmi.io/v1/subscriptions \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "account_id": "account_abc123", "rate_plan_id": "plan_xyz789", "agent_instance_ids": ["instance_123"] }' ``` # Webhooks Source: https://docs.valmi.io/docs/api-reference/webhooks Subscribe to events via webhooks ## Webhook Events Valmi Value can send webhooks for the following events: * `invoice.created` - Invoice generated * `invoice.paid` - Invoice paid * `outcome.completed` - Outcome achieved * `payment.successful` - Payment processed * `subscription.created` - Subscription created * `subscription.updated` - Subscription updated * `subscription.cancelled` - Subscription cancelled ## Configuring Webhooks 1. Navigate to **Settings** → **Webhooks** 2. Click **Add Webhook** 3. Configure: * **URL**: Your webhook endpoint * **Events**: Which events to subscribe to * **Secret**: Webhook secret for verification 4. Save ## Webhook Payload Webhooks send POST requests with JSON payloads: ```json theme={null} { "event": "invoice.created", "timestamp": "2024-01-15T10:30:00Z", "data": { "invoice_id": "inv_abc123", "account_id": "account_xyz789", "amount": 1000.00, "currency": "USD" } } ``` ## Webhook Security Verify webhook authenticity using the webhook secret: ```python theme={null} import hmac import hashlib def verify_webhook(payload, signature, secret): expected_signature = hmac.new( secret.encode(), payload.encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected_signature) ``` ## Webhook Retries Webhooks are retried if your endpoint returns an error: * **Retry Schedule**: 1min, 5min, 15min, 1hr, 6hr, 24hr * **Max Retries**: 6 attempts * **Timeout**: 30 seconds per attempt ## Testing Webhooks Test webhooks using the webhook test endpoint: ```bash theme={null} curl -X POST https://api.valmi.io/v1/webhooks/test \ -H "Authorization: Bearer sk_api_abc123xyz" \ -H "Content-Type: application/json" \ -d '{ "webhook_id": "webhook_abc123", "event": "invoice.created" }' ``` # Accounts & Subscriptions Source: https://docs.valmi.io/docs/concepts/accounts-subscriptions Managing customer accounts and subscription lifecycles ## Accounts An `account` represents a customer organization. When you create an account, you provide the company name, billing address, and contact information. Each account can have multiple contacts like billing contacts who receive invoices or technical contacts who get notifications. ## Subscriptions A `subscription` connects a customer account to a `product` and `rate plan`. When you create a subscription, you select the account, choose the product and rate plan, and set the billing cycle. The subscription starts tracking usage and accumulating charges immediately. You can update subscriptions anytime. Customers can upgrade or downgrade their rate plan, or change their billing cycle. When subscriptions change mid-cycle, charges are prorated automatically. You can pause subscriptions temporarily or cancel them permanently. ## Invoice Generation Invoices are generated automatically at the end of each billing cycle. The system adds up all the `@outcome` and `@action` usage from that period, applies the charges from the rate plan, adds any discounts, and creates an invoice. # Agent Types & Agent Instances Source: https://docs.valmi.io/docs/concepts/agents-and-instances Understanding agent types and how they're deployed ## Agent Types An **Agent Type** is a logical definition of an AI service you offer. Think of it as a template that describes what your AI can do. Agent types come in different flavors: * **LangGraph Agents** - Built with the LangGraph framework * **CrewAI Agents** - Multi-agent systems using CrewAI * **n8n Workflows** - Automated workflows with AI steps * **Custom Agents** - Any AI application using the SDK ## Agent Instances An **Agent Instance** is a specific deployment of an agent type. It's where your agent actually runs. Common instance types: * **Production** - Live customer-facing deployment * **Staging** - Testing and development environment * **Per-Customer** - Dedicated instance for a specific customer * **Multi-Tenant** - Shared instance serving multiple customers Each instance gets its own unique **secret token**. You use this token in SDK calls to identify which instance is sending events. Pricing rules come from products, which are associated with agent types. Each instance tracks usage and costs separately. ### Mapping Secret Tokens to Instances You configure the secret token when initializing the Value client. Set the `VALUE_AGENT_SECRET` environment variable to your instance's secret token: ```python theme={null} import os from value import initialize_async # Set the secret token via environment variable os.environ["VALUE_AGENT_SECRET"] = "agent_abc123xyz" # Initialize the client value = await initialize_async() ``` Or import ValueClient and pass the secret directly during initialization: ```python theme={null} from value import ValueClient value = await ValueClient.initialize_async(secret="agent_abc123xyz") ``` Once configured, the client automatically uses this token for all actions you send. The Control Plane uses this token to: * Look up the instance * Attribute usage to that instance * Track costs for that instance Secret tokens are credentials. Keep them secure and rotate them periodically. # Architecture Source: https://docs.valmi.io/docs/concepts/architecture How Valmi Value works under the hood ## How It Works Valmi **Value** is built around three simple pieces that work together seamlessly. You integrate our lightweight SDK into your agents, and everything else happens automatically. ### 1. The SDK The SDK runs alongside your agents, collecting usage data as things happen. It's invisible by design—non-blocking, reliable, and fast. It automatically captures **outcomes** (successful hires, qualified leads, conversions, or any business result you define) along with LLM calls, tokens, and actions in real-time. If your connection drops, it buffers locally and syncs when you're back online. The SDK is designed to be non-blocking and have minimal performance impact on your agents. ### 2. The Control Plane A fully managed service that processes your usage data and **outcomes**, applies your pricing rules (including **outcome-based pricing**), and generates invoices automatically. You manage everything through a simple dashboard—no servers to configure, no infrastructure to maintain. It's SaaS that scales with you automatically. Key capabilities: * Tracks profitability in real-time—see which outcomes drive revenue * Generates invoices based on outcomes, usage, or both ### 3. The Extension Framework Connects Valmi **Value** to the tools you already use. Invoices automatically go to Stripe for payment, payments sync to QuickBooks, and usage changes update your CRM. Built on the open-source valext protocol, so you can build custom integrations or use community-built ones. ### The Complete Flow Your agent performs an action and achieves an **outcome** (e.g., successful hire, qualified lead). The SDK captures the action, usage, and **outcome** instantly. The Control Plane processes it and applies pricing—including **outcome-based pricing**. Invoices generate automatically, payments flow through your existing systems, and you see everything in real-time. **You focus on your product. We handle the infrastructure.** # Billing System Source: https://docs.valmi.io/docs/concepts/billing-system Understanding products, rate plans, charges, and billing cycles ## Billing System You create a `product` to represent what you're selling. Each `product` is connected to an `agent type`, which defines what kind of AI service it represents. ### Products and Rate Plans Each `product` is associated with `rate plans`. A `rate plan` defines how customers are charged for that product. You might have a Basic plan, a Pro plan, and an Enterprise plan for the same product. Each `rate plan` has its own `currency`, so you can charge different customers in different currencies. ### Charges and Charge Models Each `rate plan` can have multiple `charges`. A `charge` is a specific line item that customers are billed for. Each `charge` is associated with a `charge model`, which is the pricing model that determines how the charge is calculated. For example, you might have a charge for `@outcome` using a `per-unit pricing` model that charges \$50 per outcome. Or you might have a charge for `@action` using a `tiered pricing` model with different rates at different volume levels. ### Billing Cycles `Billing cycles` define when customers are charged. You can set up monthly, quarterly, or annual billing cycles. Usage is aggregated over the billing cycle period, and invoices are generated at the end of each cycle. ### Proration When customers change their subscription mid-cycle, charges are prorated automatically. If they upgrade from a \$100 plan to a \$200 plan halfway through the month, they pay \$50 for the first half and \$100 for the second half. ### Simulate Charge When adding charges to a `rate plan`, you can simulate how the charge will work before saving it. The simulation shows you what revenue and costs would look like over a date range based on the charge model you're configuring. You provide a date range and the charge details you want to test. The system calculates what the charges would be for that period and shows you the revenue and cost breakdown day by day. This helps you understand if your pricing is set up correctly before you commit to it. For example, if you're adding a new charge for `@outcome` with `per-unit pricing` at \$50 per outcome, you can simulate it to see how much revenue you'd generate if customers achieved 100 outcomes in a month versus 500 outcomes. ### Discounts You can also configure discounts on charges. These are applied automatically when invoices are generated. # Cost Allocation Source: https://docs.valmi.io/docs/concepts/cost-allocation How costs are attributed to actions ## Cost Allocation Cost allocation is performed on the Control Plane for each @action. This lets you understand what each action costs and track profitability. ### Allocating Costs You can allocate costs in different ways as per Unit of Measure Allocate costs based on a specific metric from your actions: * Per token (input tokens, output tokens, or total tokens) * Per API call #### Per Token For LLM usage, allocate costs based on token consumption: The Control Plane automatically calculates costs as per automatic traces from the value-client-sdk. #### Per Unit Allocate a fixed cost per action: * \$0.05 per action * \$0.10 per API call ### How It Works When an action is processed, the Control Plane: 1. Applies the cost allocation rules you've configured 2. Calculates the cost for that Action This gives you visibility into costs at the action level, which helps you understand profitability and optimize pricing. # Metering Data Model Source: https://docs.valmi.io/docs/concepts/metering-data-model How usage data is structured and collected ## Collecting Actions ### Explicit Tracking The SDK collects explicit actions that you define in your code. Use the action context manager to track discrete units of work: ```python theme={null} with self.client.action(anonymous_id=anonymous_id, user_id=user_id) as span: span.send( action_name="object_detection", **{ "value.action.description": f"Detected {box_count} objects in {invoice_id}", "invoice_id": invoice_id, "model": "yolov8-invoice", "confidence_score": confidence, "detected_boxes": box_count, "processing_device": "cuda:0" } ) ``` Each action tracks both `anonymous_id` and `user_id` to identify who performed the action. This allows you to attribute usage to specific users even when they're not authenticated. ### Automatic LLM Tracking LLM traces are automatically tracked by the SDK. You don't need to manually instrument LLM calls. The SDK captures model usage, input and output tokens, latency, cost information, and other LLM-specific metadata. ## Computed Data Model Based on the actions you send and the Control Plane configuration, the following data model is computed: ### @action A discrete unit of work performed by your agent, explicitly tracked via the SDK or automatically captured from LLM traces. Examples: * Object detection in an invoice processing workflow * LLM call to generate a response * Image classification task * Data extraction from a document * API call to an external service ### @outcome A business result derived from actions, computed by the Control Plane based on configured outcome rules. Examples: * Successful invoice processed (derived from object\_detection actions) * Customer query resolved (derived from LLM call actions) * Document classified correctly (derived from classification actions) * Lead converted to customer (derived from multiple actions) * Task completed successfully (derived from workflow actions) ### @user An end user of your service, identified by `user_id` or `anonymous_id` in actions, used for per-user usage tracking and billing. Examples: * Authenticated user with `user_id="user_123"` * Anonymous visitor with `anonymous_id="anon_456"` * API client identified by `user_id="api_client_789"` * Internal user with `user_id="internal_team_001"` ### @seat A billing unit representing a licensed user, computed from user activity and seat assignment rules configured in the Control Plane. Examples: * Active user who has used the service in the last 30 days * User assigned a seat based on role or department # What is Valmi Value? Source: https://docs.valmi.io/docs/concepts/overview A high-level overview of the Valmi Value platform Valmi **Value** is a complete billing and payments infrastructure platform built specifically for AI agents and AI-powered applications. Unlike traditional billing systems, Valmi **Value** understands the unique requirements of AI workloads, including token-based usage, outcome-based pricing, and complex cost attribution. # Pricing & Charge Models Source: https://docs.valmi.io/docs/concepts/pricing-rating-models How pricing works and different pricing models ## Pricing Models Valmi Value supports three types of pricing models: Usage-based, Recurring, and One-time. Each model supports different charge types that determine how customers are billed. ### Usage-Based Pricing Usage-based pricing is built on the computed data models: `@action`, `@outcome`, `@seat`, and `@user`. This model emphasizes `outcome-based pricing`, where you charge customers based on business results achieved by your agents. `Outcome-based pricing` charges customers for business results like successful hires, converted leads, or completed tasks. For example, charge \$500 per successful hire or \$50 per converted lead. You can also charge based on `@action`, `@seat`, or `@user` if needed. `Per-unit pricing` charges a fixed amount for each unit. Charge \$500 per `@outcome`, \$0.01 per `@action`, \$10 per `@seat`, or \$5 per `@user`. `Tiered pricing` applies different rates at different volume levels. The first 100 `@outcome` might cost \$50 each, the next 400 cost \$40 each, and anything above that costs \$30 each. `Volume pricing` charges different prices per unit based on which volume tier the total usage falls into. If total usage is 0-500 `@outcome`, charge \$50 per `@outcome`. If total usage is 500-1,000 `@outcome`, charge \$40 per `@outcome` for everything in that tier. If total usage exceeds 1,000 `@outcome`, charge \$30 per `@outcome` for everything in that tier. `Discounts` can be applied as a percentage or flat amount off the total charges. ### Recurring Pricing Recurring pricing charges customers on a regular schedule, like monthly or annually. This model supports different charge types. `Flat fee` is a fixed amount charged each billing period. For example, charge \$99 per month or \$999 per year regardless of usage. `Overage pricing` combines a base fee with usage charges. You might charge \$99 per month that includes 10,000 actions for free, then charge \$0.01 per action above that limit. `Discounts` can reduce the recurring charges by a percentage or flat amount. ### One-Time Pricing One-time pricing charges customers a single time for a purchase or service. This model supports two charge types. `Flat fee` is a fixed one-time charge. For example, charge \$500 for a setup fee or \$1,000 for a one-time project. `Discounts` can reduce the one-time charge by a percentage or flat amount. ## Charge Process When actions or outcomes are recorded, the charge engine identifies which pricing rules apply, calculates the charges based on the pricing model, applies any discounts, and records the charges for invoice generation. # Problem Statement Source: https://docs.valmi.io/docs/concepts/problem-statement The challenges AI platforms face with billing and payments ## The Billing Challenge You've built something amazing. Your AI agents are solving real problems, customers are using them, and you're ready to scale. But there's a problem: **traditional billing systems weren't built for what you're doing.** ### What Traditional Systems Can't Handle * Systems like Stripe Billing or Zuora don't understand tokens, or outcomes * They're built for simple subscriptions and straightforward usage patterns * Your world is more complex ### What You Actually Need * Track LLM costs that vary by model and provider * Attribute costs to specific agents and customers * **Price based on outcomes**—charge for successful hires, qualified leads, or actual conversions—not just raw usage * Understand which parts of your business are actually profitable ### The Outcome-Based Pricing Challenge Traditional billing systems force you to charge for usage (tokens, API calls, compute time). But your customers care about **outcomes**: * A successful hire, not the number of resumes reviewed * A qualified lead, not the number of emails sent * A completed transaction, not the number of API calls You need to bill for what matters—the value you deliver, not the infrastructure you use. This requires tracking outcomes, attributing costs to them, and pricing accordingly. Most systems can't do this. ### The Cost of Flying Blind Without proper cost attribution: * You can't tell which agents make money * You can't identify which customers are profitable * You don't know how your margins change as you scale * You end up building custom solutions that take months and cost a fortune * Your team gets pulled away from building great AI products **The result?** You spend more time wrestling with billing infrastructure than building features your customers want. That's the problem we're solving. # Revenue & Profitability Source: https://docs.valmi.io/docs/concepts/revenue-profitability Understanding margin analysis and PnL reporting ## Revenue & Profitability The platform tracks `revenue` from what customers pay and `costs` from what you spend on LLM providers, APIs, and infrastructure. It calculates your `margin` by subtracting costs from revenue. You can view profitability by `agent type`, by `customer`, or by `product` and `rate plan`. This shows you which parts of your business are making money and which need attention. Costs can be viewed as `blended costs` which show the average, or as `itemized costs` which break down LLM costs, API costs, and infrastructure separately. This helps you see where your money is going. You can track profitability over time with weekly, monthly, or quarterly views to spot trends and make decisions. # What Valmi Value Provides Source: https://docs.valmi.io/docs/concepts/what-valmi-provides The complete solution for AI billing and payments ## Your Complete Billing Infrastructure Valmi **Value** gives you everything you need to turn your AI agents into a real business. Instead of spending months building custom billing systems, you get a complete solution that understands how AI actually works. ### Outcome-Based Pricing (Front and Center) **Charge for what matters—the value you deliver, not just the infrastructure you use.** Track and bill for outcomes: successful hires, qualified leads, completed transactions, or any business result. The SDK automatically captures outcomes as they happen, and you can price based on outcomes while still tracking underlying costs (tokens, API calls, compute). Set different rates for different outcomes to reward high-value results. Your customers pay for success, not just usage. Key benefits: * Align your pricing with customer value, not your infrastructure costs * Price based on business results, not just raw usage ### Automatic Usage Tracking The SDK automatically captures every action, token, and outcome as it happens. You see usage in real-time, and everything flows seamlessly into pricing and billing. No manual tracking, no spreadsheets, no guesswork. ### Flexible Pricing Models Price however makes sense for your business. Use **outcome-based pricing** to charge for successful hires, qualified leads, conversions, or any business result. Or charge per token, per action, per outcome, or any combination. Set up tiered pricing that rewards volume, or create hybrid models with base subscriptions plus usage or outcomes. Test different pricing strategies before you commit—the system handles the complexity so you can focus on what works for your customers. ### Automated Billing Invoices generate on schedule or on-demand with your branding and custom templates. Taxes are handled automatically, prorations are automatic, and credits and discounts apply correctly. Your customers get professional invoices that reflect the value you're delivering. ### Business Intelligence See exactly which agents are profitable and which customers drive the most value. Track margins in real-time and make data-driven decisions about pricing, product development, and customer relationships. Connect to payment processors, accounting systems, and CRMs without building custom integrations. ### Zero Infrastructure Management You get all of this without: * Managing infrastructure * Maintaining complex systems * Hiring a billing team **Focus on building great AI products. We'll handle the rest.** # On-Prem deployment Source: https://docs.valmi.io/docs/deployment/on-premise-deployment Managing development, staging, and production environments ## Multi-Environment Support Valmi Value supports multiple environments for development, staging, and production. ## Environment Types ### Development * **Purpose**: Local development and testing * **Data**: Test data only * **Keys**: Development API keys * **Isolation**: Separate from production ### Staging * **Purpose**: Pre-production testing * **Data**: Production-like test data * **Keys**: Staging API keys * **Isolation**: Separate from production ### Production * **Purpose**: Live customer-facing environment * **Data**: Real customer data * **Keys**: Production API keys * **Isolation**: Fully isolated ## Environment Configuration ### Separate Accounts Use separate Valmi Value accounts for each environment: * **Development Account**: For development * **Staging Account**: For staging * **Production Account**: For production ### Separate API Keys Use different API keys per environment: ```python theme={null} import os # Get key from environment variable api_key = os.getenv("VALMI_API_KEY") # Development: VALMI_API_KEY=sk_test_dev_abc123 # Staging: VALMI_API_KEY=sk_test_staging_xyz789 # Production: VALMI_API_KEY=sk_live_prod_def456 value = ValueClient(api_key=api_key) ``` ### Separate Agent Keys Use different agent keys per environment: ```python theme={null} # Development agent_key = os.getenv("VALMI_AGENT_KEY_DEV", "agent_dev_abc123") # Staging agent_key = os.getenv("VALMI_AGENT_KEY_STAGING", "agent_staging_xyz789") # Production agent_key = os.getenv("VALMI_AGENT_KEY_PROD", "agent_prod_def456") value.send_action(agent_key=agent_key, ...) ``` ## Environment Variables Use environment variables for configuration: ```bash theme={null} # Development export VALMI_API_KEY="sk_test_dev_abc123" export VALMI_AGENT_KEY="agent_dev_abc123" export VALMI_ENV="development" # Staging export VALMI_API_KEY="sk_test_staging_xyz789" export VALMI_AGENT_KEY="agent_staging_xyz789" export VALMI_ENV="staging" # Production export VALMI_API_KEY="sk_live_prod_def456" export VALMI_AGENT_KEY="agent_prod_def456" export VALMI_ENV="production" ``` ## Environment Isolation Environments are fully isolated: * **Data Isolation**: No data sharing between environments * **Key Isolation**: Keys only work in their environment * **Configuration Isolation**: Separate configuration per environment ## Best Practices * **Separate Accounts**: Use separate accounts for each environment * **Different Keys**: Use different keys per environment * **Environment Variables**: Use environment variables for configuration * **No Production Data in Dev**: Never use production data in development * **Test in Staging**: Always test in staging before production * **Document Configuration**: Document environment configuration ## Deployment Workflow 1. **Development**: Develop and test locally 2. **Staging**: Deploy to staging for integration testing 3. **Production**: Deploy to production after staging validation ## Environment Management Manage environments: * **Create Environments**: Set up new environments as needed * **Sync Configuration**: Keep configuration in sync (where appropriate) * **Monitor Separately**: Monitor each environment independently * **Rotate Keys**: Rotate keys per environment # Building Your Own Extension Source: https://docs.valmi.io/docs/extensions/building-extensions How to build custom valext extensions **Coming Soon**: Extensions are not currently available. This feature is under development and will be released soon. # How valext Works Source: https://docs.valmi.io/docs/extensions/how-valext-works Understanding the valext extension protocol **Coming Soon**: Extensions are not currently available. This feature is under development and will be released soon. ## valext Protocol valext is an open-source extension protocol that defines how extensions interact with Valmi Value and external systems. > **Note**: The extension system is currently under development. The information below is a preview of what will be available. ## Event-Driven Architecture Extensions are event-driven and react to events from Valmi Value: ### Event Types * `invoice.created` - New invoice generated * `invoice.paid` - Invoice payment received * `outcome.completed` - Business outcome achieved * `subscription.created` - New subscription * `subscription.updated` - Subscription changed * `payment.successful` - Payment processed ### Event Payload Events include: * **Event Type**: What happened * **Timestamp**: When it happened * **Data**: Event-specific data * **Metadata**: Additional context ## Extension Lifecycle ### 1. Registration Extensions register with Valmi Value: * Provide extension metadata * Subscribe to event types * Configure authentication ### 2. Event Reception When events occur: * Valmi Value sends event to extension * Extension receives event via webhook or polling * Extension validates event authenticity ### 3. Processing Extension processes event: * Transforms data to external system format * Calls external system API * Handles errors and retries ### 4. Response Extension reports result: * Success: Event processed successfully * Failure: Error occurred (with retry) * Status: Processing status updates ## Metadata Contracts Extensions use standardized metadata formats: ### Invoice Metadata ```json theme={null} { "invoice_id": "inv_abc123", "account_id": "account_xyz789", "amount": 1000.00, "currency": "USD", "line_items": [...], "due_date": "2024-02-15" } ``` ### Payment Metadata ```json theme={null} { "payment_id": "pay_abc123", "invoice_id": "inv_xyz789", "amount": 1000.00, "currency": "USD", "payment_method": "stripe", "transaction_id": "txn_123" } ``` ## Mapping to Upstream Systems Extensions map Valmi Value data to external system formats: ### Stripe Mapping ```python theme={null} def map_to_stripe(invoice): return { "amount": int(invoice.amount * 100), # Convert to cents "currency": invoice.currency.lower(), "customer": invoice.account.stripe_customer_id, "metadata": { "valmi_invoice_id": invoice.id } } ``` ### QuickBooks Mapping ```python theme={null} def map_to_quickbooks(invoice): return { "Line": [ { "Amount": invoice.amount, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": {"value": "1"} } } ], "CustomerRef": {"value": invoice.account.quickbooks_id} } ``` ## Error Handling Extensions handle errors gracefully: * **Retries**: Automatic retry with exponential backoff * **Dead Letter Queue**: Failed events stored for manual review * **Notifications**: Alert on persistent failures * **Logging**: Comprehensive error logging ## Extension Configuration Extensions are configured per account or globally: * **API Keys**: External system credentials * **Mapping Rules**: How to transform data * **Retry Policies**: How to handle failures * **Filters**: Which events to process # What Are Extensions? Source: https://docs.valmi.io/docs/extensions/what-are-extensions Introduction to valext extensions **Coming Soon**: Extensions are not currently available. This feature is under development and will be released soon. ## Extensions Overview **Extensions** (built on the valext protocol) connect Valmi Value to external systems like payment processors, accounting software, CRMs, and other business tools. > **Note**: The extension system is currently under development. The information below is a preview of what will be available. ## Available Extensions All extensions are currently in development and will be available soon. ### Payment Processors * **Stripe Extension**: Process payments, handle subscriptions, manage customers \[Coming Soon] * **PayPal Extension**: Accept PayPal payments \[Coming Soon] * **Other Processors**: Square, Braintree, etc. \[Coming Soon] ### Accounting Systems * **QuickBooks Extension**: Sync invoices and payments to QuickBooks \[Coming Soon] * **Xero Extension**: Sync to Xero accounting \[Coming Soon] * **NetSuite Extension**: Enterprise ERP integration \[Coming Soon] ### CRM Systems * **HubSpot Extension**: Sync customer data and usage to HubSpot \[Coming Soon] * **Salesforce Extension**: Integrate with Salesforce CRM \[Coming Soon] ### Other Systems * **Slack Extension**: Send notifications to Slack \[Coming Soon] * **Email Extension**: Send custom email notifications \[Coming Soon] * **Custom Extensions**: Build your own extensions \[Coming Soon] ## What Extensions Do Extensions enable: * **Payment Processing**: Automatically charge customers when invoices are generated * **Accounting Sync**: Keep your books in sync automatically * **CRM Integration**: Update customer records with usage and billing data * **Notifications**: Alert your team about important events * **Custom Workflows**: Build custom integrations for your needs ## How Extensions Work Extensions are event-driven: 1. **Event Occurs**: Something happens in Valmi Value (invoice created, payment received, etc.) 2. **Extension Triggered**: The extension receives the event 3. **Action Taken**: Extension performs an action (charge customer, update CRM, send notification) 4. **Result Recorded**: Extension reports success or failure ## Extension Architecture Extensions support bidirectional data flow: ### Outbound Flow (Valmi Value → External System) ``` Valmi Value → Event → valext Extension → External System ↓ Response/Status ``` ### Inbound Flow (External System → Valmi Value) Extensions can also work as ingestion into Valmi Value through webhooks: ``` External System → Webhook → valext Extension → Valmi Value ↓ Response/Status ``` Extensions run as separate services that: * Subscribe to Valmi Value events (outbound) * Receive webhooks from external systems (inbound) * Transform data to match external system formats * Call external system APIs * Handle errors and retries * Report status back to Valmi Value # Analyze Profit and Loss Source: https://docs.valmi.io/docs/guides/analyze-profit-and-loss Use PnL analysis to understand revenue, costs, and profitability ## Analyze Profit and Loss PnL Analysis helps you understand the profitability of your AI services by comparing revenue from customers against the costs of running your agents. This guide shows you how to navigate the PnL dashboard, filter data by agent type and customer, and interpret the charts and metrics. ## Step 1: Navigate to PnL Analysis Go to **PnL analysis** in the left sidebar. The dashboard opens with a chart showing revenue, costs, and margin percentage over time, along with aggregate summary cards at the bottom. PnL Analysis dashboard showing chart with revenue, cost, and margin percentage, along with filters and aggregate summary The page displays "Analyze profit and loss with revenue, cost, and margin percentage" at the top, followed by filter controls and the main visualization. ## Step 2: Filter by Date Range and Grouping At the top of the page, you'll find filter controls. Set the date range using the **From** and **To** date pickers to analyze a specific time period. The **Group By** dropdown lets you aggregate data by Daily, Weekly, or Monthly intervals. Daily grouping shows day-by-day trends, while monthly grouping provides a higher-level overview. The **Currency** dropdown lets you view all amounts in your preferred currency, such as USD or EUR. This is useful when you have customers in different regions. ## Step 3: Filter by Agent Type Use the **Agent Type** dropdown to focus on a specific agent. Select "OCR Agent" to see profitability for just that agent, or leave it blank to see data across all agents. This helps you identify which agents are most profitable and which might need optimization. When you change the agent type, the chart updates automatically to show revenue, costs, and margin percentage for that specific agent over the selected date range. ## Step 4: Filter by Customer Account The **Account** dropdown lets you filter by customer. Select "Acme Corp" to see profitability for that specific customer, or leave it blank to see aggregated data across all customers. This is useful for understanding which customers are most valuable and which relationships might need attention. Combining account and agent type filters lets you drill down into specific customer-agent combinations to see exactly how profitable each relationship is. ## Step 5: Understanding the Chart The main chart displays three metrics over time. Purple vertical bars represent **Revenue**, showing how much you're billing customers. Green vertical bars represent **Costs**, showing your expenses for LLMs, APIs, and infrastructure. The orange line with circular markers shows **Margin %**, which is the profitability percentage calculated as (Revenue - Cost) / Revenue × 100. The chart has two Y-axes: the left axis shows amounts in dollars, and the right axis shows margin percentage. Positive margin percentages indicate profitability, while negative values mean costs exceed revenue for that period. Hover over any data point to see exact values for that date. ## Step 6: Aggregate Summary Below the chart, the Aggregate Summary section provides an overview of the entire filtered period. The donut chart on the left visualizes total revenue. The summary cards on the right show three key metrics: **Total Revenue** displays the sum of all customer billing, **Total Cost** shows your total expenses, and **Total Margin** shows the difference along with the margin percentage. A positive margin percentage in green indicates overall profitability, while a negative percentage in red means costs exceed revenue. Use these numbers to quickly assess whether your current pricing and cost structure are sustainable. # Configure Outcomes and Cost Allocation Source: https://docs.valmi.io/docs/guides/configure-outcomes-cost-allocation Set up action tagging, cost allocation, and outcome definitions for your agents ## Configure Outcomes and Cost Allocation This guide shows you how to configure your metering setup so the platform can properly track costs and identify outcomes. You'll set up action tagging, assign costs to actions, and define which actions represent business outcomes. ## Step 1: Go to Metering Navigate to **Metering** in the left sidebar. This is where you configure all your metering settings. You'll see four tabs: Live Data, Action Tagging, Cost Allocation, and Outcome Definitions. We'll work through the last three tabs to set everything up. ## Step 2: Assign Auto Tags to Actions In the **Action Tagging** tab, you'll see a list of all the actions your agent is performing. These come from two sources: auto tags that the SDK automatically creates, and trace events from your LLM calls. Action Tagging interface showing auto tags and trace events Each action has a toggle switch. Turn on the toggles for the actions you want to track. For example, you might enable `gemini_llm_gemini-2.5-flash` to track Gemini LLM calls, or `gemini.generate_content` to track content generation. The actions you enable here will be available for cost allocation and outcome definitions. When you're done, you'll see a green checkmark with "Saved" indicating your changes are saved. ## Step 3: Assign Cost Allocation In the **Cost Allocation** tab, you assign costs to each action. This tells the platform how much each action costs you, which is essential for profitability analysis. Cost Allocation interface showing actions with measure and cost fields For each action, you select a measure and set a cost. The measure can be `token` for LLM calls, `unit` for other actions, or other units of measure. Then you enter the cost per unit. For example, `gemini_llm_gemini-2.5-flash` might use `token` as the measure with a cost of `0.006` per token. An `object_classification` action might use `unit` as the measure with a cost of `0.003` per unit. The platform uses these costs to calculate your expenses and show you profitability. When you're done, you'll see a green checkmark with "Saved". ## Step 4: Assign Outcomes In the **Outcome Definitions** tab, you define which actions represent business outcomes. Outcomes are the business results you care about, like successful hires, converted leads, or completed tasks. Outcome Definitions interface showing actions with outcome toggles You'll see a list of all your actions. Toggle on the actions that represent outcomes. For example, if `object_detection` represents a successful outcome in your workflow, turn on its toggle. The platform will then track these as `@outcome` in addition to `@action`, which allows you to price based on outcomes. When you're done configuring, you'll see a green checkmark with "Saved". Your metering is now fully configured. The platform will track costs for all your actions and identify outcomes automatically. # Create Customer Dashboard Source: https://docs.valmi.io/docs/guides/create-customer-dashboard Build custom dashboards for customers and share them via magic links ## Create Customer Dashboard Create custom dashboards for customer accounts and share them through secure magic links. ## Step 1: Go to Customer Dashboards Navigate to **Embeds** in the left sidebar. Embeds page showing dashboard creation interface ## Step 2: Create a New Dashboard Click **Create Dashboard** or **"+ Create"** and select the customer account from the dropdown. ## Step 3: Customize Charts Add and configure charts for outcomes, actions, seats, users, and costs. Each chart can be set to different time ranges, grouping intervals, and visualization styles like bar, line, area, or stacked charts. Dashboard editor showing customizable charts for outcomes, actions, seats, users, and costs Drag panels to rearrange charts and resize them as needed. Click **Save** when done. ## Step 4: Generate Magic Link After saving, click **Generate Magic Link** to create a secure link for the customer account. Magic link generation interface showing link options and access settings The magic link automatically authenticates the customer contact and shows only data for their account. Copy and share the link with the customer contact. When they click it, they'll be logged in and see their dashboard without needing a password. # Create Customer Subscription Source: https://docs.valmi.io/docs/guides/create-customer-subscription Add a subscription to a customer account to start billing ## Create Customer Subscription Once you have products and rate plans set up, you need to create subscriptions to connect customers to those plans. This guide shows you how to add a subscription to a customer account. ## Step 1: Go to Subscriptions Navigate to **Accounts > Subscriptions** in the left sidebar. You'll see a list of all subscriptions, both active and archived. Subscriptions list showing active subscriptions The subscriptions list shows each subscription's name, which account it belongs to, what rate plan it uses, and the trigger that created it. You can filter by customer to see only specific accounts. Click the **"+ Create"** button to add a new subscription. ## Step 2: Add a Rate Plan to the Account The create subscription form opens. Select the account you want to create a subscription for. This is the customer who will be billed. Create subscription form with account, rate plan, trigger, and name fields Choose the rate plan from the dropdown. This determines how the customer will be charged. The rate plan shows which product it belongs to, like "ocr product • Starter plan". Select a trigger that determines when this subscription becomes active. Common triggers include "CustomerSigned" for when a customer signs up, or you can set it to activate immediately. Give the subscription a name that helps you identify it, like "acme corp ocr product". This name appears in your subscriptions list and helps you track which subscription belongs to which customer. Click **"Create"** to finish. The subscription is now active and will start tracking usage and generating invoices according to the billing cycle in the rate plan. # Customize Invoices and Taxes Source: https://docs.valmi.io/docs/guides/customize-invoices-and-taxes Configure tax rates, customize invoice templates, and generate invoices ## Customize Invoices and Taxes This guide walks you through configuring tax rates for your customers, customizing invoice templates to match your brand, and generating invoices. You'll set up taxes, create a custom invoice template using markdown, and learn how to view and manage generated invoices. ## Configure Tax Rates Navigate to **Billing > Taxes** in the left sidebar. This page shows all tax configurations for your accounts and subscriptions. Taxes configuration page showing account, subscription, and tax rate fields Each row represents a tax configuration for a specific account and subscription. The tax rate is displayed as a percentage. To modify a tax rate, click on the input field and enter the new percentage value, or use the up and down arrows to adjust it. For example, you might set an 18% tax rate for "Acme Corp" on their "acme corp ocr product" subscription. Click **Save** in the top right corner when you're done making changes. The tax rates you configure here will automatically be applied when invoices are generated. ## Customize Invoice Templates Navigate to **Billing > Templates** to create or edit invoice templates. Invoice templates use markdown format, making it easy to customize the layout and styling of your invoices. Click **Create Template** or edit an existing template. The template editor is split into two panels: the left side shows the markdown editor, and the right side shows a live preview of how the invoice will look. Invoice template editor with markdown on the left and preview on the right The markdown editor has two tabs: **Markdown** for the template content and **CSS Styles** for custom styling. In the markdown, you can use placeholders like `{{invoice_number}}`, `{{billing_name}}`, `{{issue_date}}`, and `{{due_date}}` to insert dynamic data into your invoices. You can also use custom block delimiters like `::: bill-to` and `::: ship-to` to create sections for billing and shipping addresses. The `::: items` block is used for the line items table. As you type in the markdown editor, the preview panel updates in real-time to show how the invoice will appear with sample data. Once you're satisfied with your template, click **Create** to save it. The template will be used when generating invoices. ## Generate and View Invoices Navigate to **Billing > Invoice** to view bill runs and invoice history. A bill run is a process that generates invoices for a specific billing period. To create a new bill run, click the **"+ Create"** button in the top right. A modal will open where you can configure the bill run details. Create Invoice modal with company name, bill date, and invoice date fields Select the company name from the dropdown, choose the bill date range (the period you're billing for), and set the invoice date. Click **Create** to generate the bill run. The bill run will appear in the "Bill Runs" section with a status like "Pending" while it's being processed. Invoice page showing bill runs table and invoice history section Once a bill run is complete, the generated invoices will appear in the "Invoice History" section below. You can view each invoice, download it as a PDF, and see all the details including line items, taxes, and totals. If you need to modify an invoice or create a custom bill run, you can issue a new bill run with different parameters. This allows you to adjust billing periods, update charges, or regenerate invoices as needed. # Getting Started with Metering Source: https://docs.valmi.io/docs/guides/getting-started-metering Set up your first agent and start tracking usage in four simple steps ## Getting Started with Metering This guide walks you through setting up your first agent and seeing usage data in real-time. You'll create an agent type, deploy an instance, integrate the SDK, and view live metering data. ## Step 1: Create Agent Type An agent type defines what kind of AI service you're offering. It's like a template that describes your agent's capabilities. Navigate to **Agents > Types > Create New**. Fill in the form with your agent details. Give it a name like "OCR Agent" and a description that explains what it does. The type field identifies the agent framework or technology you're using. Create Agent Type form Once you create the agent type, it's ready to use. You can create multiple instances from a single agent type. ## Step 2: Create Agent Instance An agent instance is a specific deployment of your agent type. This is where your agent actually runs and sends usage data. Navigate to **Agents > Instances > Create New**. Fill in the instance details. Give it a name like "OCR Agent instance for Acme" and select the agent type you created. You can also associate it with an account and contact if you have those set up. Create Agent Instance form When you create the instance, you'll receive a secret token. This token identifies which instance is sending events. Keep it secure. ## Step 3: Integrate SDK Install the Valmi Value Python SDK and configure it with your instance's secret token. First, install the SDK: ```bash theme={null} pip install valmi-value ``` Then configure the secret token when initializing the Value client. Set the `VALUE_AGENT_SECRET` environment variable to your instance's secret token: ```python theme={null} import os from value import initialize_async # Set the secret token via environment variable os.environ["VALUE_AGENT_SECRET"] = "agent_abc123xyz" # Initialize the client value = await initialize_async() ``` Or import ValueClient and pass the secret directly during initialization: ```python theme={null} from value import ValueClient value = await ValueClient.initialize_async(secret="agent_abc123xyz") ``` Once configured, the client automatically uses this token for all actions you send. Start sending actions from your agent code and the SDK will track usage automatically. ## Step 4: View Live Metering Once your agent is running and sending events, you can see the data in real-time. Navigate to **Metering > Live Data**. Select your agent instance from the dropdown. You'll see a live stream of all actions as they happen, with details like timestamps, action IDs, and metadata. Live Data view showing real-time metering events The live data view shows events as they arrive, with columns for created\_at, id, measure, and other metadata fields. You can filter the data, customize which columns are visible, and see usage happening in real-time. That's it. You're now tracking usage for your agent. The data you see here is what gets used for billing, cost allocation, and profitability analysis. # Setup Outcome-Based Billing Source: https://docs.valmi.io/docs/guides/setup-outcome-based-billing Create a product, rate plan, and charges for outcome-based pricing ## Setup Outcome-Based Billing This guide walks you through setting up outcome-based billing from scratch. You'll create a product, add a rate plan, and configure charges that bill customers based on `@outcome` achievements. ## Step 1: Go to Product Catalog Navigate to **Product > Product Catalog** in the left sidebar. This is where you manage all your products and their pricing. You'll see a list of existing products, or an empty list if you're starting fresh. ## Step 2: Add a Product Click the **"+ Create"** button to create a new product. A modal will open where you define what you're selling. Create Product modal with product details form Fill in the product details. Give it a name like "ocr product" and a description that explains what the product does. Set the default effective date, which is when the product becomes available. Most importantly, select the `agent type` this product is associated with. This connects the product to your agent type so the platform knows which agents this pricing applies to. Click **"Create product"** when you're done. The product is now created and ready for rate plans. ## Step 3: Add a Rate Plan Open your product to see its details page. You'll see a section for rate plans. Click **"New rate plan"** to create one. Create rate plan modal with plan details form A modal opens where you configure the rate plan. Give it a name like "Starter plan" and a description. Set the effective date, which is when this plan becomes active. Choose a billing cycle like Monthly, Quarterly, or Annual. This determines how often customers are billed. Click **"Save"** to create the rate plan. You'll see it appear on the product detail page. ## Step 4: Add Charges With your rate plan created, you can now add charges. Click **"+ Add charge"** on your rate plan. Add charge modal with charge configuration form The charge configuration form opens. Give your charge a name like "outcome charge" and a description. Select the currency, typically USD. Choose "Usage" as the charge type since you're billing based on usage. Select "Tiered" as the model type for tiered pricing, or choose another pricing model that fits your needs. Most importantly, set the **Unit of measure** to `@outcome`. This tells the platform to charge based on outcomes achieved, not just actions performed. If you selected tiered pricing, configure your tiers. Each tier has a start value, an end value, and a price per unit. For example, the first 100 outcomes might cost \$50 each, the next 400 cost \$40 each, and anything above that costs \$30 each. Before saving, you can click **"Simulate"** to see how the charge would work with sample usage data. This helps you verify your pricing is correct. When you're ready, click **"Save"** to add the charge. Product detail page showing rate plan with charge added Your charge now appears in the rate plan. The platform will use this charge configuration to bill customers based on the `@outcome` they achieve. When customers use your agent and achieve outcomes, they'll be charged according to the pricing tiers you've set up. # Simulate Charge Pricing Source: https://docs.valmi.io/docs/guides/simulate-charge-pricing Test different pricing configurations before deploying them to customers ## Simulate Charge Pricing Before you commit to a pricing change, you can simulate how it will affect revenue and costs. This guide shows you how to test different price points and see the impact on your margins. ## Step 1: Go to Rate Plan Navigate to your product in **Product > Product Catalog**. Open the product to see its detail page. You'll see all the rate plans associated with that product. Click on the rate plan you want to test, like "Starter plan". Product detail page showing rate plan with charges You'll see the rate plan details and all the charges it contains. Each charge shows its current configuration, including the pricing model and unit of measure. ## Step 2: Edit Charge Find the charge you want to test and click the **"Edit"** button. This opens the charge configuration modal where you can modify the pricing. Edit charge modal with pricing configuration The edit modal shows all the charge settings. You can change the currency, charge type, model type, and most importantly, the pricing configuration. For tiered pricing, you'll see all your tiers with their start values, end values, and prices. ## Step 3: Change Price Modify the prices in your tiers to test different scenarios. For example, if your first tier currently charges \$10 per `@outcome` for the first 100 outcomes, you might change it to \$15 to see how that affects revenue. You can adjust any tier's price using the up and down arrows, or type directly into the price field. You can also add new tiers or remove existing ones. The changes you make here are only for simulation - they won't be saved until you click "Save". ## Step 4: Simulate Click the **"Simulate"** button to see how your pricing changes would work. The simulation opens in a new view. Simulate charge interface with revenue, cost, and margin chart Set the date range you want to simulate, like from October 2 to December 2. Choose how to group the data - daily, weekly, or monthly. Select which charges to include in the simulation. Click **"Run Simulation"** and the platform calculates what revenue and costs would look like with your new pricing. You'll see a chart showing revenue bars, cost bars, and a margin percentage line over time. This helps you understand if your pricing changes improve profitability or if you need to adjust further. Once you're happy with the simulation results, go back to the edit modal and click **"Save"** to apply the changes. If the simulation shows the pricing isn't working as expected, you can adjust the prices and simulate again until you find the right balance. # Introduction Source: https://docs.valmi.io/docs/introduction Valmi **Value** - Outcome-Based Billing & Payments Infrastructure for AI Agents ## About Valmi **Value** Valmi **Value** is outcome-billing and payments infrastructure for AI agents. We handle metering, pricing, billing, and revenue tracking so you can focus on building great AI products. ## Core Benefits Understands tokens, LLM activity, API calls, and outcomes—built for AI from the ground up. Usage-based, tiered, per-action, per-outcome, or any combination that works for your business. Automatically track costs across LLM providers, APIs, and compute. Real-time profitability tracking per agent and per customer. ## Who is this for? Valmi Value is for teams building AI Agents and workflows. Get started with just **5 lines of code**—minimal developer work, maximum iteration power. * **Product Teams** - Launch consumption-based pricing models without building billing infrastructure * **Revenue Teams** - Track profitability, margins, and revenue per customer in real-time * **Agent Developers** - Add flexible billing and cost tracking with minimal code changes * **AI Platform Teams** - Meter, price, and bill accurately across all your AI services ## Components Overview **Open-source** lightweight SDK that collects usage data from your agents. Works with LangGraph, CrewAI, n8n, and custom apps. SaaS dashboard for pricing, billing, invoicing, and analytics. No infrastructure to manage. Open-source protocol to connect with payment processors, CRMs, accounting tools, and more. ## Get Started Ready to start billing your AI agents? Follow our [Quick Start Guide](/docs/quickstart) to get running in minutes. # Quick Start Source: https://docs.valmi.io/docs/quickstart Get up and running with Valmi Value in under 5 minutes This guide will walk you through the complete setup process to send your first meter event, create an agent, set up billing, and generate your first invoice. ## 2.1 Installing the SDK Install the Valmi Value Python SDK: ```bash theme={null} pip install valmi-value ``` Python 3.8+ is required. Support for Node.js, Go, and other languages coming soon. ## 2.2 Send Your First Meter Event ```python theme={null} from valmi_value import ValueClient from langgraph.graph import StateGraph # Initialize the Value client value = ValueClient(api_key="your-api-key") # In your agent workflow def agent_node(state): # Your agent logic here result = llm.invoke(state["messages"]) # Send meter event value.send_action( agent_key="my-langgraph-agent", action_type="llm_call", metadata={ "model": "gpt-4", "input_tokens": result.usage.prompt_tokens, "output_tokens": result.usage.completion_tokens, "cost_usd": calculate_cost(result.usage) } ) return {"messages": result} ``` ## 2.3 Create Your First Agent 1. Log in to the [Valmi Value Control Plane](https://cloud.valmi.io) 2. Navigate to **Agents** → **Create Agent** 3. Fill in the agent details: * **Name**: My First Agent * **Type**: LangGraph Agent * **Description**: A simple agent for testing 4. Click **Create** You'll receive an Agent Key that you'll use in your SDK calls. Keep this secure! ## 2.4 Attach Metering to the Agent 1. In the Agent details page, copy the **Agent Key** 2. Update your code to use this key: ```python theme={null} value = ValueClient(api_key="your-api-key") value.send_action( agent_key="agent_abc123xyz", # Your agent key action_type="llm_call", metadata={...} ) ``` 3. Events will start appearing in the **Live Data** view within seconds ## 2.5 Set Up a Billing Plan 1. Navigate to **Products** → **Create Product** 2. Create a new product: * **Product Name**: AI Agent API * **Description**: Pay-per-use AI agent service 3. Create a **Rate Plan**: * **Plan Name**: Usage-Based Plan * **Pricing Model**: Usage-Based * **Charge**: \$0.01 per 1,000 tokens 4. Save the plan ## 2.6 Create an Account + Subscription 1. Go to **Accounts** → **Create Account** 2. Fill in account details: * **Account Name**: Acme Corp * **Contact Email**: [billing@acme.com](mailto:billing@acme.com) 3. Click **Create Subscription**: * Select your product and rate plan * Set billing cycle (monthly) * Assign the agent instance to this subscription 4. Save the subscription ## 2.7 Generate First Invoice 1. Navigate to **Billing** → **Invoices** 2. Click **Run Invoice** for the current billing period 3. The system will: * Aggregate all usage for the period * Apply pricing rules * Calculate costs and revenue * Generate the invoice 4. View and download the invoice PDF ## 2.8 View Revenue & Margin 1. Go to **Profit & Loss** dashboard 2. You'll see: * **Revenue**: Total billed amount * **Costs**: LLM and infrastructure costs * **Margin**: Revenue - Costs * **Margin %**: Profitability percentage 3. Filter by agent, customer, or time period Congratulations! You've successfully set up Valmi Value and generated your first invoice. Explore the [Core Concepts](/concepts/overview) section to learn more about how everything works. # Agent Keys & Mapping Source: https://docs.valmi.io/docs/sdk/agent-keys-mapping Understanding agent keys and how to use them ## What are Agent Keys? An **Agent Key** is a unique identifier for an agent instance. It's used in SDK calls to identify which agent instance is sending events. ## Getting Your Agent Key 1. Log in to the [Valmi Value Control Plane](https://cloud.valmi.io) 2. Navigate to **Agents** → Select an agent → **Instances** 3. Create or select an instance 4. Copy the **Agent Key** Agent keys are secret credentials. Keep them secure and never commit them to version control. ## Using Agent Keys Use the agent key in SDK calls: ```python theme={null} value.send_action( agent_key="agent_abc123xyz", # Your agent key action_type="llm_call", metadata={...} ) ``` ## Environment-Based Keys Use different keys for different environments: ```python theme={null} import os # Get key from environment agent_key = os.getenv("VALMI_AGENT_KEY", "agent_abc123xyz") value.send_action( agent_key=agent_key, action_type="llm_call", metadata={...} ) ``` ## Key Mapping The Control Plane maps agent keys to: * **Agent Instance**: Which instance the key belongs to * **Pricing Rules**: Instance-specific pricing * **Cost Allocation**: How costs are attributed * **Subscriptions**: Which customer subscription (if any) ## Key Rotation Periodically rotate agent keys for security: 1. In the Control Plane, navigate to the instance 2. Click **Rotate Key** 3. New key is generated 4. Old key is invalidated (with 24-hour grace period) 5. Update your code with the new key There's a 24-hour grace period where both old and new keys work, giving you time to update your code. ## Multiple Instances Use different keys for different instances: ```python theme={null} # Production instance value.send_action( agent_key="agent_prod_abc123", action_type="llm_call", metadata={...} ) # Staging instance value.send_action( agent_key="agent_staging_xyz789", action_type="llm_call", metadata={...} ) ``` ## Key Validation The SDK validates agent keys: * **Format Check**: Validates key format * **Existence Check**: Verifies key exists (on first use) * **Status Check**: Ensures key is active Invalid keys will result in errors when sending events. ## Best Practices * **Store Securely**: Use environment variables or secret management * **Rotate Regularly**: Rotate keys every 90 days * **Use Different Keys**: Separate keys for different environments * **Monitor Usage**: Track key usage in the Control Plane # SDK Guarantees Source: https://docs.valmi.io/docs/sdk/guarantees Delivery guarantees, buffering, and error handling ## Delivery Guarantees The Valmi Value SDK provides **at-least-once delivery**: * Events are guaranteed to be delivered at least once * Events may be delivered multiple times (deduplication handled server-side) * Events are never lost (buffered locally if API unavailable) ## Offline Buffering Events are automatically buffered locally when: * Network is unavailable * API is temporarily down * Rate limits are hit ### Buffer Behavior * **Automatic Buffering**: Events are stored locally * **Automatic Retry**: SDK retries sending buffered events * **Buffer Size**: Configurable buffer size (default: 100 events) * **Flush Interval**: Automatic flush every N seconds (default: 5) ### Buffer Configuration ```python theme={null} value = ValueClient( api_key="sk_live_abc123xyz", buffer_size=1000, # Buffer up to 1000 events flush_interval=10, # Flush every 10 seconds ) ``` ## Retry Logic The SDK automatically retries failed requests: * **Max Retries**: Configurable (default: 3) * **Exponential Backoff**: Retries with increasing delays * **Retryable Errors**: Network errors, 5xx status codes * **Non-Retryable Errors**: 4xx errors (except rate limits) ### Retry Configuration ```python theme={null} value = ValueClient( api_key="sk_live_abc123xyz", max_retries=5, # Retry up to 5 times retry_delay=1, # Initial retry delay in seconds ) ``` ## Deduplication Server-side deduplication prevents duplicate events: * **Event IDs**: Each event gets a unique ID * **Deduplication Window**: 24-hour deduplication window * **Automatic Handling**: No action required from you ## Error Handling ### Network Errors Network errors are handled automatically: * Events are buffered locally * SDK retries when connection is restored * No data loss ### Invalid Requests Invalid requests return errors: ```python theme={null} try: value.send_action( agent_key="invalid_key", action_type="llm_call", metadata={...} ) except ValueError as e: # Invalid agent key or parameters print(f"Error: {e}") ``` ### Rate Limiting Rate limits are handled gracefully: * Events are buffered when rate limited * SDK automatically retries with backoff * No data loss ## Manual Flush Manually flush buffered events: ```python theme={null} # Flush all buffered events immediately value.flush() ``` ## Graceful Shutdown Close the client gracefully: ```python theme={null} # Flush remaining events and close value.close() ``` Or use context manager: ```python theme={null} with ValueClient(api_key="sk_live_abc123xyz") as value: value.send_action(...) # Automatically flushes and closes ``` ## Performance The SDK is designed for performance: * **Non-Blocking**: Sends events asynchronously * **Batch Support**: Efficient batch sending * **Minimal Overhead**: Low performance impact * **Connection Pooling**: Reuses connections ## Monitoring Monitor SDK health: * **Event Count**: Track events sent * **Error Rate**: Monitor error rates * **Buffer Size**: Monitor buffer usage * **Retry Count**: Track retry attempts # Initialization Source: https://docs.valmi.io/docs/sdk/initialization Initializing the Valmi Value SDK client ## Basic Initialization Initialize the SDK with your API key: ```python theme={null} from valmi_value import ValueClient value = ValueClient(api_key="sk_live_abc123xyz") ``` ## Configuration Options Configure the client with additional options: ```python theme={null} value = ValueClient( api_key="sk_live_abc123xyz", api_url="https://api.valmi.io", # Optional: custom API URL timeout=30, # Request timeout in seconds max_retries=3, # Number of retry attempts buffer_size=100, # Local buffer size for events flush_interval=5, # Seconds between automatic flushes ) ``` ## Environment Variables Use environment variables for configuration: ```bash theme={null} export VALMI_API_KEY="sk_live_abc123xyz" export VALMI_API_URL="https://api.valmi.io" ``` Then initialize without explicit API key: ```python theme={null} from valmi_value import ValueClient value = ValueClient() # Reads VALMI_API_KEY from environment ``` ## Async Initialization For async applications: ```python theme={null} from valmi_value import AsyncValueClient value = AsyncValueClient(api_key="sk_live_abc123xyz") ``` ## Context Manager Use as a context manager for automatic cleanup: ```python theme={null} with ValueClient(api_key="sk_live_abc123xyz") as value: value.send_action(...) # Client automatically flushes and closes ``` ## Client Methods Once initialized, the client provides: * `send_action()` - Send action events * `send_outcome()` - Send outcome events * `flush()` - Manually flush buffered events * `close()` - Close the client and flush remaining events # Installation Source: https://docs.valmi.io/docs/sdk/installation Installing the Valmi Value Python SDK ## Python SDK Installation Install the Valmi Value Python SDK using pip: ```bash theme={null} pip install valmi-value ``` ## Requirements * **Python**: 3.8 or higher * **pip**: Latest version recommended ## Verify Installation Verify the installation: ```python theme={null} import valmi_value print(valmi_value.__version__) ``` ## Updating the SDK Update to the latest version: ```bash theme={null} pip install --upgrade valmi-value ``` ## Development Installation For development, install from source: ```bash theme={null} git clone https://github.com/valmi-io/value-sdk-python cd value-sdk-python pip install -e . ``` ## Other Languages SDKs for other languages are coming soon: * **Node.js**: Coming Q2 2024 * **Go**: Coming Q3 2024 * **Java**: Coming Q4 2024 Subscribe to our updates to be notified when new SDKs are released. # Language Integrations Source: https://docs.valmi.io/docs/sdk/language-integrations Integrating with LangGraph, CrewAI, n8n, and custom applications ## LangGraph Integration Integrate Valmi Value with LangGraph agents: ```python theme={null} from valmi_value import ValueClient from langgraph.graph import StateGraph value = ValueClient(api_key="sk_live_abc123xyz") def agent_node(state): # Your agent logic result = llm.invoke(state["messages"]) # Meter the LLM call value.send_action( agent_key="my-langgraph-agent", action_type="llm_call", metadata={ "model": "gpt-4", "input_tokens": result.usage.prompt_tokens, "output_tokens": result.usage.completion_tokens, "cost_usd": calculate_cost(result.usage) } ) return {"messages": result} ``` ### LangGraph Middleware Create middleware for automatic metering: ```python theme={null} from valmi_value import ValueClient class ValmiMiddleware: def __init__(self, agent_key): self.value = ValueClient(api_key="sk_live_abc123xyz") self.agent_key = agent_key def on_llm_call(self, state, result): self.value.send_action( agent_key=self.agent_key, action_type="llm_call", metadata={ "model": result.model, "input_tokens": result.usage.prompt_tokens, "output_tokens": result.usage.completion_tokens } ) ``` ## CrewAI Integration Integrate with CrewAI agents: ```python theme={null} from valmi_value import ValueClient from crewai import Agent, Task, Crew value = ValueClient(api_key="sk_live_abc123xyz") class MeteredAgent(Agent): def execute(self, task): result = super().execute(task) # Meter the agent execution value.send_action( agent_key="crew-research-agent", action_type="agent_execution", metadata={ "task": task.description, "tools_used": len(self.tools), "execution_time_ms": result.execution_time } ) return result ``` ### CrewAI Task Metering Meter individual tasks: ```python theme={null} def execute_task_with_metering(task, agent): start_time = time.time() result = agent.execute(task) execution_time = (time.time() - start_time) * 1000 value.send_action( agent_key="crew-agent", action_type="task_execution", metadata={ "task_id": task.id, "execution_time_ms": execution_time, "success": result.success } ) return result ``` ## n8n Integration Integrate with n8n workflows: ```python theme={null} from valmi_value import ValueClient value = ValueClient(api_key="sk_live_abc123xyz") # In your n8n workflow node async def execute(self): start_time = time.time() # Your workflow logic result = await process_data(self.inputData) execution_time = (time.time() - start_time) * 1000 # Meter the workflow execution value.send_action( agent_key="n8n-workflow", action_type="workflow_execution", metadata={ "workflow_id": self.workflow.id, "node_id": self.node.id, "execution_time_ms": execution_time, "nodes_executed": len(self.executedNodes) } ) return result ``` ### n8n Custom Node Create a custom n8n node for metering: ```python theme={null} class ValmiMeterNode: def execute(self, data): value = ValueClient(api_key=self.credentials.api_key) value.send_action( agent_key=self.parameters.agent_key, action_type=self.parameters.action_type, metadata=json.loads(self.parameters.metadata) ) return data ``` ## Custom Integration Integrate with any Python application: ```python theme={null} from valmi_value import ValueClient value = ValueClient(api_key="sk_live_abc123xyz") def my_ai_function(input_data): # Your AI logic result = process_with_ai(input_data) # Meter the operation value.send_action( agent_key="my-custom-agent", action_type="ai_processing", metadata={ "input_size": len(input_data), "output_size": len(result), "processing_time_ms": calculate_time() } ) return result ``` ## Decorator Pattern Use decorators for automatic metering: ```python theme={null} from valmi_value import ValueClient from functools import wraps value = ValueClient(api_key="sk_live_abc123xyz") def meter_action(agent_key, action_type): def decorator(func): @wraps(func) def wrapper(*args, **kwargs): start_time = time.time() result = func(*args, **kwargs) execution_time = (time.time() - start_time) * 1000 value.send_action( agent_key=agent_key, action_type=action_type, metadata={ "function": func.__name__, "execution_time_ms": execution_time } ) return result return wrapper return decorator # Use the decorator @meter_action("my-agent", "custom_function") def my_function(): # Your code pass ``` ## Context Manager Pattern Use context managers for scoped metering: ```python theme={null} from valmi_value import ValueClient value = ValueClient(api_key="sk_live_abc123xyz") class MeteredContext: def __init__(self, agent_key, action_type): self.agent_key = agent_key self.action_type = action_type self.start_time = None def __enter__(self): self.start_time = time.time() return self def __exit__(self, *args): execution_time = (time.time() - self.start_time) * 1000 value.send_action( agent_key=self.agent_key, action_type=self.action_type, metadata={"execution_time_ms": execution_time} ) # Use the context manager with MeteredContext("my-agent", "processing"): # Your code process_data() ``` # Sending Meter Events Source: https://docs.valmi.io/docs/sdk/sending-meter-events Sending actions and outcomes from your agents ## Sending Actions Send action events to meter agent usage: ```python theme={null} value.send_action( agent_key="agent_abc123xyz", action_type="llm_call", metadata={ "model": "gpt-4", "input_tokens": 1000, "output_tokens": 500, "cost_usd": 0.06, "latency_ms": 1250 } ) ``` ### Action Parameters * **agent\_key** (required): The agent instance key * **action\_type** (required): Type of action (e.g., "llm\_call", "tool\_call") * **metadata** (optional): Key-value pairs with action details * **timestamp** (optional): Event timestamp (defaults to now) ### Common Action Types * `llm_call` - LLM API invocation * `embedding` - Vector embedding generation * `tool_call` - External tool or API call * `agent_execution` - Complete agent run * `workflow_step` - Step in a workflow * `custom` - Custom action type ## Sending Outcomes Send outcome events for business results: ```python theme={null} value.send_outcome( agent_key="agent_abc123xyz", outcome_type="successful_hire", value=1, metadata={ "candidate_id": "cand_123", "position": "Software Engineer", "salary": 120000 } ) ``` ### Outcome Parameters * **agent\_key** (required): The agent instance key * **outcome\_type** (required): Type of outcome (e.g., "successful\_hire") * **value** (required): Outcome value (count or amount) * **metadata** (optional): Additional context * **timestamp** (optional): Event timestamp (defaults to now) ## Attaching Metadata Metadata provides context about events: ### LLM Call Metadata ```python theme={null} value.send_action( agent_key="agent_abc123xyz", action_type="llm_call", metadata={ "model": "gpt-4", "provider": "openai", "input_tokens": 1000, "output_tokens": 500, "temperature": 0.7, "max_tokens": 2000, "cost_usd": 0.06, "latency_ms": 1250 } ) ``` ### Tool Call Metadata ```python theme={null} value.send_action( agent_key="agent_abc123xyz", action_type="tool_call", metadata={ "tool_name": "stripe_api", "endpoint": "create_payment", "cost_usd": 0.05, "success": True } ) ``` ### Custom Metadata Add any custom fields: ```python theme={null} value.send_action( agent_key="agent_abc123xyz", action_type="custom_action", metadata={ "customer_id": "cust_123", "workflow_id": "wf_456", "custom_field": "custom_value", "any_data": {"nested": "structure"} } ) ``` ## Batch Sending Send multiple events efficiently: ```python theme={null} actions = [ { "agent_key": "agent_abc123xyz", "action_type": "llm_call", "metadata": {...} }, { "agent_key": "agent_abc123xyz", "action_type": "tool_call", "metadata": {...} } ] value.send_actions(actions) ``` ## Async Sending For async applications: ```python theme={null} await value.send_action( agent_key="agent_abc123xyz", action_type="llm_call", metadata={...} ) ``` ## Error Handling Handle errors gracefully: ```python theme={null} try: value.send_action( agent_key="agent_abc123xyz", action_type="llm_call", metadata={...} ) except ValueError as e: # Invalid parameters print(f"Invalid action: {e}") except ConnectionError as e: # Network error - event is buffered locally print(f"Connection error: {e}") except Exception as e: # Other errors print(f"Error: {e}") ``` Events are automatically buffered locally if the API is unavailable. They'll be sent when the connection is restored. # FAQ Source: https://docs.valmi.io/docs/support/faq Frequently asked questions ## General Questions ### What is an Agent? An **Agent** is a logical grouping of AI functionality. It represents a type of AI service you offer, such as a LangGraph agent for customer support, a CrewAI agent for research, or a custom AI application. ### What is an Agent Instance? An **Agent Instance** is a specific deployment or customer-specific version of an Agent. Each instance has its own Agent Key used in SDK calls, allowing you to track usage and costs per instance. ### How does Pricing Simulation work? The Pricing Simulator lets you test pricing models with sample usage data before deploying them to customers. Enter sample usage (tokens, API calls, etc.) and see calculated charges, costs, and margins. ### When should I use Extensions vs Webhooks? **Extensions** are pre-built integrations that handle common workflows (Stripe payments, QuickBooks sync, etc.). **Webhooks** are for custom integrations where you want to receive events and handle them yourself. Use extensions for: * Common integrations (Stripe, QuickBooks, HubSpot) * Standard workflows * Quick setup Use webhooks for: * Custom integrations * Complex workflows * Full control over event handling ### How does cost allocation work? Cost allocation attributes your expenses (LLM costs, API costs, infrastructure) to specific agents, actions, or customers. LLM costs are automatically calculated when you include model and provider metadata. Other costs can be manually configured or allocated proportionally. ### What is the difference between blended and itemized costs? **Blended costs** show average cost across all usage (e.g., \$0.01 per 1K tokens). **Itemized costs** break down costs by component (LLM costs, API costs, infrastructure). Itemized costs provide better visibility into cost drivers. ### How do I handle multiple LLM providers? Include `provider` and `model` in action metadata. The system automatically applies the correct pricing based on provider rates. You can also create separate charges for different models if you want different customer pricing. ### Can I bill in multiple currencies? Yes, Valmi Value supports multi-currency pricing and billing. You can set prices in different currencies and generate invoices in customer's preferred currency. ### How do I test my integration? 1. Use a test/staging environment 2. Send test events from your agent 3. Verify events appear in Live Data 4. Test pricing with Pricing Simulator 5. Generate test invoices ### What happens if the API is down? The SDK automatically buffers events locally when the API is unavailable. Events are retried when the connection is restored. No data is lost. ### How do I rotate API keys? 1. Create a new API key 2. Update all applications with the new key 3. Test to verify everything works 4. Revoke the old key There's a 24-hour grace period where both keys work, giving you time to update. ### Can I use Valmi Value for non-AI services? While Valmi Value is optimized for AI agents, you can use it for any consumption-based billing use case. The flexible metadata system allows you to meter and price any type of usage. ### How do I get support? * **Documentation**: Check our comprehensive documentation * **Slack Community**: Join our [Slack Community](https://www.valmi.io/slack) * **GitHub Issues**: Report issues on [GitHub](https://github.com/valmi-io/value/issues) * **Email**: Contact [support@valmi.io](mailto:support@valmi.io) ### Is there a free tier? Yes, Valmi Value offers a free tier for development and testing. See [pricing](https://www.valmi.io/pricing) for details. ### What compliance certifications does Valmi Value have? Valmi Value is SOC 2 Type II compliant and GDPR compliant. Additional certifications (HIPAA, ISO 27001) are coming in 2024. # Roadmap Source: https://docs.valmi.io/docs/support/roadmap Upcoming features and improvements ## 1. Python SDK * Client side per request cost override ## 2. Upcoming Libraries * Node.js SDK * Golang SDK ## 3. Control Plane Enhancements and new features for the Control Plane interface. #### Multi-Currency Enhancements * Real-time exchange rates * Multi-currency invoices * Currency conversion reporting #### Plan Experiments * A/B testing for pricing plans * Experiment analytics * Automatic winner selection #### Usage Aggregation Rules * Custom aggregation rules * Time-based aggregation * Dimension-based aggregation #### Advanced Analytics * Predictive analytics * Anomaly detection * Custom dashboards #### Extension Marketplace * Public extension marketplace * Community-contributed extensions * Extension ratings and reviews #### White-Label Options * Custom branding * White-label Control Plane * Custom domains #### Enterprise Features * Advanced security * SSO/SAML support * Enterprise support #### Additional Compliance * SOC 2 Type II * ISO 27001 * HIPAA (for healthcare) ## 4. Valext Extension Protocol Improvements and updates to the Valext extension protocol for building custom integrations. #### Performance Improvements * Faster invoice generation * Improved query performance * Better scalability ## 6. Feature Requests Have a feature request? Let us know: * **GitHub Issues**: [github.com/valmi-io/value/issues](https://github.com/valmi-io/value/issues) * **Slack Community**: [Slack Community](https://www.valmi.io/slack) * **Email**: [contact@valmi.io](mailto:contact@valmi.io) ## 7. Voting Vote on features in our [public roadmap](https://github.com/valmi-io/value/issues). Features with the most votes get prioritized. ## 8. Beta Programs Join beta programs for early access: * **Beta Features**: Test new features before release * **Early Access**: Get access to features in development * **Feedback**: Help shape product direction Sign up: [www.valmi.io/#featureset](https://www.valmi.io/#featureset)