CostShield

Pre-execution cost governance for AI agent tool calls.

CostShield enforces budget limits before costs are incurred — not after. It is a pre-execution enforcement mechanism that prevents runaway LLM inference, API, and business operation costs.

Part of the Faramesh governance ecosystem.

Features

Community (Open Source — No Account Required)

• Session budget limits — cap per-session spend with automatic enforcement
• Daily budget limits — hard daily spend ceilings per agent
• Per-tool cost declarations — fixed, per-token, and business cost models
• Two-phase cost accounting — reserve before execution, settle to actuals
• LLM inference budgets — token limits, per-call caps, session LLM spend
• DPR-compatible audit records — every cost decision is fully auditable
• Local mesh connectivity — seamless integration with other Faramesh tools

Pro (Faramesh Cloud Account Required)

• Rolling window budgets — sliding N-minute spend limits
• Cross-service aggregate budgets — unified $ across all tools/agents
• Cloud cost sync — cost data synced to Faramesh Cloud for dashboards

Team Plan

• Cost anomaly detection — ML-powered spend anomaly alerts
• Budget forecasting — projected cost trajectory with confidence intervals

Enterprise Plan

• Fleet-wide budgets — coordinated budget enforcement across agent fleets
• Compliance cost reporting — cost governance audit exports

Quick Start

package main

import (
    "context"
    "fmt"
    "github.com/faramesh/costshield"
)

func main() {
    tracker := costshield.NewTracker(costshield.TrackerConfig{
        Budget: costshield.BudgetConfig{
            SessionLimitUSD: 50.00,
            DailyLimitUSD:   500.00,
            OnExceed:        costshield.ExceedDeny,
        },
        ToolCosts: map[string]costshield.ToolCost{
            "openai/chat": {
                Type:           costshield.CostTypePerToken,
                CostPer1KInput: 0.03,
                ChargeOn:       costshield.ChargeOnAttempt,
            },
        },
    })

    decision, err := tracker.Check(context.Background(), costshield.CostRequest{
        AgentID:          "payment-bot",
        SessionID:        "session-123",
        ToolID:           "openai/chat",
        EstimatedCostUSD: 0.12,
        EstimatedTokens:  4000,
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Effect: %s (reserved: $%.2f)\n", decision.Effect, decision.ReservedUSD)
}

Cloud Integration

// With Faramesh Cloud — unlocks advanced features based on your plan
tracker, err := costshield.NewCloudTracker(costshield.TrackerConfig{
    Budget: costshield.BudgetConfig{
        SessionLimitUSD:      50.00,
        DailyLimitUSD:        500.00,
        RollingWindowMinutes: 60,      // Pro feature
        RollingLimitUSD:      100.00,  // Pro feature
    },
})

// Register in local mesh for inter-tool communication
tracker.RegisterMesh("1.0.0")

Inter-Tool Mesh

CostShield automatically connects with other Faramesh tools running locally:

• Core sends cost-check requests before permitting tool calls
• Tesseract feeds observation data for cost estimation
• Sverm coordinates cross-agent budget enforcement

// Other tools can query CostShield via the mesh
mesh, _ := cloud.NewMesh(cloud.ToolCore)
payload, _ := json.Marshal(costshield.CostRequest{...})
result, _ := mesh.Send(ctx, cloud.MeshMessage{
    To:      cloud.ToolCostShield,
    Type:    "cost.check",
    Payload: payload,
})

Install

go get github.com/faramesh/costshield@latest

License

Apache License 2.0