ledgrr 0.1.0__py3-none-any.whl

ledgrr/__init__.py

@@ -0,0 +1,29 @@
+"""
+Ledgrr — Financial observability for AI systems.
+ledgrr.io
+"""
+
+from .event import BillingEvent, FinancialStatus, GSTType, OperationalStatus
+from .instrument import Ledgrr
+from .ledger import DuplicateEventError, Ledger
+from .dlq import DeadLetterQueue
+from .pricing import compute_usd_cost
+from .track import track_llm, configure
+
+__version__ = "0.2.0"
+__all__ = [
+    # Primary interface
+    "track_llm",
+    "configure",
+    # Class-based interface
+    "Ledgrr",
+    "Ledger",
+    "DeadLetterQueue",
+    # Types
+    "BillingEvent",
+    "FinancialStatus",
+    "OperationalStatus",
+    "GSTType",
+    "DuplicateEventError",
+    "compute_usd_cost",
+]

ledgrr/api.py

@@ -0,0 +1,316 @@
+"""
+api.py — FastAPI server for the Ledgrr hosted control plane.
+
+This wraps the SDK into a real HTTP API so customers can use
+Ledgrr from any language — not just Python.
+
+Endpoints:
+  POST /events              — Ingest a billing event
+  GET  /events/{customer_id}/{period} — Get events for a customer
+  GET  /totals/{customer_id}/{period} — Get cost totals
+  GET  /breakdown/users/{customer_id}/{period} — Per-user breakdown
+  GET  /breakdown/models/{customer_id}/{period} — Per-model breakdown
+  POST /invoices/generate   — Generate a GST invoice
+  POST /invoices/submit-irp — Submit invoice to IRP
+  GET  /invoices/{invoice_number}/irn — Get IRN status
+  GET  /health              — Health check
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+from fastapi.middleware.cors import CORSMiddleware
+
+from fastapi import FastAPI, HTTPException, Header
+from pydantic import BaseModel
+
+from .event import BillingEvent, FinancialStatus, GSTType, OperationalStatus
+from .idempotency import generate_event_id
+from .invoice import InvoiceGenerator
+from .irp import IRPClient
+from .ledger import DuplicateEventError, Ledger
+
+
+# ─── App ─────────────────────────────────────────────────────────────────────
+
+app = FastAPI(
+    title="Ledgrr API",
+    description="Financial infrastructure for Indian AI companies",
+    version="0.1.0",
+)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Shared ledger instance — in production this connects to PostgreSQL
+ledger = Ledger()
+
+# IRP client — in production this uses real GSP credentials
+irp_client = IRPClient(
+    gstin="29AABCL1234A1Z5",
+    simulate=True,
+)
+
+# In-memory invoice store — in production this uses DB
+_invoices: dict = {}
+
+
+# ─── Request / Response Models ────────────────────────────────────────────────
+
+class IngestEventRequest(BaseModel):
+    """Ingest a billing event from the SDK."""
+    event_id: str
+    idempotency_key: str
+    event_type: str
+    provider_request_id: str
+    provider: str
+    model: str
+    customer_id: str
+    user_id: str
+    billing_period: str
+    input_tokens: int
+    output_tokens: int
+    cached_input_tokens: int = 0
+    usd_cost: float
+    fx_rate_snapshot: float
+    fx_snapshot_date: str
+    inr_cost: float
+    gst_type: str = "IGST"
+    gst_rate: float = 0.18
+    gst_component: float = 0.0
+    gstin_customer: Optional[str] = None
+    operational_status: str = "completed"
+    financial_status: str = "pending_confirmation"
+    billable: bool = True
+    margin_inr: Optional[float] = None
+    parent_event_id: Optional[str] = None
+    created_at: str
+
+
+class GenerateInvoiceRequest(BaseModel):
+    customer_id: str
+    customer_name: str
+    billing_period: str
+    customer_gstin: Optional[str] = None
+    customer_state_code: Optional[str] = None
+    invoice_number: Optional[str] = None
+    seller_name: str = "Ledgrr Technologies Pvt Ltd"
+    seller_gstin: str = "29AABCL1234A1Z5"
+    seller_address: str = "Bangalore, Karnataka - 560001"
+    seller_state_code: str = "29"
+
+
+class SubmitIRPRequest(BaseModel):
+    invoice_number: str
+    force_retry: bool = False
+
+
+# ─── Health ──────────────────────────────────────────────────────────────────
+
+@app.get("/health")
+def health():
+    return {
+        "status": "ok",
+        "version": "0.1.0",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+# ─── Events ──────────────────────────────────────────────────────────────────
+
+@app.post("/events", status_code=201)
+def ingest_event(req: IngestEventRequest):
+    """
+    Ingest a billing event emitted by the Ledgrr SDK.
+
+    Idempotent — submitting the same event twice is safe.
+    Returns 200 if deduplicated, 201 if newly stored.
+    """
+    event = BillingEvent(
+        event_id=req.event_id,
+        idempotency_key=req.idempotency_key,
+        event_type=req.event_type,
+        provider_request_id=req.provider_request_id,
+        provider=req.provider,
+        model=req.model,
+        customer_id=req.customer_id,
+        user_id=req.user_id,
+        billing_period=req.billing_period,
+        input_tokens=req.input_tokens,
+        output_tokens=req.output_tokens,
+        cached_input_tokens=req.cached_input_tokens,
+        usd_cost=req.usd_cost,
+        fx_rate_snapshot=req.fx_rate_snapshot,
+        fx_snapshot_date=req.fx_snapshot_date,
+        inr_cost=req.inr_cost,
+        gst_type=GSTType(req.gst_type),
+        gst_rate=req.gst_rate,
+        gst_component=req.gst_component,
+        gstin_customer=req.gstin_customer,
+        operational_status=OperationalStatus(req.operational_status),
+        financial_status=FinancialStatus(req.financial_status),
+        billable=req.billable,
+        margin_inr=req.margin_inr,
+        parent_event_id=req.parent_event_id,
+        created_at=datetime.fromisoformat(req.created_at),
+    )
+
+    try:
+        ledger.append(event)
+        return {"status": "stored", "event_id": event.event_id}
+    except DuplicateEventError:
+        return {"status": "deduplicated", "event_id": event.event_id}
+
+
+@app.get("/events/{customer_id}/{period}")
+def get_events(customer_id: str, period: str, billable_only: bool = True):
+    """Get all events for a customer in a billing period."""
+    events = ledger.get_events_for_customer(
+        customer_id=customer_id,
+        billing_period=period,
+        billable_only=billable_only,
+    )
+    return {
+        "customer_id": customer_id,
+        "billing_period": period,
+        "count": len(events),
+        "events": [e.to_dict() for e in events],
+    }
+
+
+# ─── Totals & Breakdowns ──────────────────────────────────────────────────────
+
+@app.get("/totals/{customer_id}/{period}")
+def get_totals(customer_id: str, period: str):
+    """
+    Get aggregated cost totals for a customer in a billing period.
+
+    Returns total INR cost, GST, and total with GST.
+    This is the primary endpoint for the margin dashboard.
+    """
+    return ledger.get_total_cost_inr(
+        customer_id=customer_id,
+        billing_period=period,
+    )
+
+
+@app.get("/breakdown/users/{customer_id}/{period}")
+def get_user_breakdown(customer_id: str, period: str):
+    """Per-user cost breakdown — shows which users drive the most AI spend."""
+    breakdown = ledger.get_cost_by_user(
+        customer_id=customer_id,
+        billing_period=period,
+    )
+    return {
+        "customer_id": customer_id,
+        "billing_period": period,
+        "users": breakdown,
+    }
+
+
+@app.get("/breakdown/models/{customer_id}/{period}")
+def get_model_breakdown(customer_id: str, period: str):
+    """Per-model cost breakdown — use for model routing decisions."""
+    breakdown = ledger.get_cost_by_model(
+        customer_id=customer_id,
+        billing_period=period,
+    )
+    return {
+        "customer_id": customer_id,
+        "billing_period": period,
+        "models": breakdown,
+    }
+
+
+# ─── Invoices ────────────────────────────────────────────────────────────────
+
+@app.post("/invoices/generate", status_code=201)
+def generate_invoice(req: GenerateInvoiceRequest):
+    """
+    Generate a GST invoice for a customer's billing period.
+
+    Reads from ledger — reproducible from same ledger state.
+    GST type (IGST vs CGST+SGST) determined automatically from state codes.
+    """
+    generator = InvoiceGenerator(
+        ledger=ledger,
+        seller_name=req.seller_name,
+        seller_gstin=req.seller_gstin,
+        seller_address=req.seller_address,
+        seller_state_code=req.seller_state_code,
+    )
+
+    try:
+        invoice = generator.generate(
+            customer_id=req.customer_id,
+            customer_name=req.customer_name,
+            billing_period=req.billing_period,
+            customer_gstin=req.customer_gstin,
+            customer_state_code=req.customer_state_code,
+            invoice_number=req.invoice_number,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+    # Store invoice in memory for IRP submission
+    _invoices[invoice.invoice_number] = invoice
+
+    return invoice.to_dict()
+
+
+@app.post("/invoices/submit-irp")
+def submit_to_irp(req: SubmitIRPRequest):
+    """
+    Submit an invoice to the Indian IRP for IRN generation.
+
+    Handles:
+    - Idempotent resubmission (same invoice_number = cached result)
+    - Automatic retry on IRP timeouts
+    - Permanent failure detection (invalid GSTIN etc.)
+    """
+    invoice = _invoices.get(req.invoice_number)
+    if not invoice:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Invoice {req.invoice_number} not found. Generate it first via POST /invoices/generate",
+        )
+
+    result = irp_client.submit(invoice, force_retry=req.force_retry)
+
+    return {
+        "success": result.success,
+        "invoice_number": result.invoice_number,
+        "irn": result.irn,
+        "ack_number": result.ack_number,
+        "ack_date": result.ack_date,
+        "qr_code": result.qr_code,
+        "error_code": result.error_code,
+        "error_message": result.error_message,
+        "retryable": result.retryable,
+        "attempts_made": result.attempts_made,
+    }
+
+
+@app.get("/invoices/{invoice_number}/irn")
+def get_irn_status(invoice_number: str):
+    """Get the IRN submission status for an invoice."""
+    history = irp_client.get_submission_history(invoice_number)
+
+    if not history:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No IRP submission history found for invoice {invoice_number}",
+        )
+
+    latest = history[-1]
+    return {
+        "invoice_number": invoice_number,
+        "status": latest.status.value,
+        "irn": latest.irn,
+        "ack_number": latest.ack_number,
+        "ack_date": latest.ack_date,
+        "attempts": len(history),
+        "latest_error": latest.error_message,
+    }

ledgrr/cli.py

@@ -0,0 +1,258 @@
+"""
+cli.py — Ledgrr command-line tools.
+
+Usage:
+    python -m ledgrr.cli replay --from 2026-05-01
+    python -m ledgrr.cli diff invoice_123
+    python -m ledgrr.cli dlq
+    python -m ledgrr.cli totals --workspace org_abc --period 2026-05
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from decimal import Decimal
+
+from .ledger import Ledger
+from .dlq import DeadLetterQueue
+from .invoice import InvoiceGenerator
+from .money import assert_invoice_matches_ledger
+
+
+def _get_ledger(args) -> Ledger:
+    db_path = getattr(args, "db", None)
+    return Ledger(db_path)
+
+
+def cmd_totals(args):
+    """Show cost totals for a workspace and period."""
+    ledger = _get_ledger(args)
+    totals = ledger.get_total_cost_inr(args.workspace, args.period)
+
+    print(f"\n{'─' * 40}")
+    print(f"  Workspace : {args.workspace}")
+    print(f"  Period    : {args.period}")
+    print(f"{'─' * 40}")
+    print(f"  INR Cost  : ₹{totals['total_inr_cost']}")
+    print(f"  GST       : ₹{totals['total_gst']}")
+    print(f"  Total     : ₹{totals['total_with_gst']}")
+    print(f"  Calls     : {totals['event_count']}")
+    print(f"{'─' * 40}\n")
+
+
+def cmd_users(args):
+    """Show per-user cost breakdown."""
+    ledger = _get_ledger(args)
+    users = ledger.get_cost_by_user(args.workspace, args.period)
+
+    if not users:
+        print(f"No billable events for {args.workspace} in {args.period}")
+        return
+
+    print(f"\n{'─' * 60}")
+    print(f"  Per-user breakdown: {args.workspace} / {args.period}")
+    print(f"{'─' * 60}")
+    print(f"  {'USER':<30} {'CALLS':>6} {'INR COST':>12}")
+    print(f"  {'─'*30} {'─'*6} {'─'*12}")
+    for u in users:
+        print(f"  {u['user_id']:<30} {u['call_count']:>6} ₹{u['total_inr_cost']:>10.4f}")
+    print(f"{'─' * 60}\n")
+
+
+def cmd_replay(args):
+    """
+    Replay all events from a date and verify ledger integrity.
+
+    This doesn't modify the ledger — it reads all events from
+    the given date and reports the deterministic totals.
+    Use this to verify your ledger hasn't drifted.
+    """
+    ledger = _get_ledger(args)
+    from_date = args.from_date
+    workspace = args.workspace
+
+    # Get all periods from the date
+    start = datetime.fromisoformat(from_date)
+    current = datetime.now(timezone.utc)
+
+    periods = []
+    year, month = start.year, start.month
+    while (year, month) <= (current.year, current.month):
+        periods.append(f"{year}-{month:02d}")
+        month += 1
+        if month > 12:
+            month = 1
+            year += 1
+
+    print(f"\n  Replaying events from {from_date}")
+    print(f"  Workspace: {workspace}")
+    print(f"{'─' * 50}")
+
+    grand_total_cost = Decimal("0")
+    grand_total_gst = Decimal("0")
+    grand_total_calls = 0
+
+    for period in periods:
+        totals = ledger.get_total_cost_inr(workspace, period)
+        if totals["event_count"] > 0:
+            print(f"  {period}: {totals['event_count']:>5} calls  "
+                  f"₹{totals['total_inr_cost']:>10.4f} + "
+                  f"₹{totals['total_gst']:>8.4f} GST")
+            grand_total_cost += Decimal(str(totals["total_inr_cost"]))
+            grand_total_gst += Decimal(str(totals["total_gst"]))
+            grand_total_calls += totals["event_count"]
+
+    print(f"{'─' * 50}")
+    print(f"  TOTAL    : {grand_total_calls:>5} calls  "
+          f"₹{grand_total_cost:>10.4f} + "
+          f"₹{grand_total_gst:>8.4f} GST")
+    print(f"  PAYABLE  : ₹{grand_total_cost + grand_total_gst:.4f}\n")
+
+
+def cmd_diff(args):
+    """
+    Diff an invoice against current ledger state.
+
+    Shows whether the invoice total still matches the ledger.
+    Use this to detect billing drift after amendments or corrections.
+    """
+    ledger = _get_ledger(args)
+    invoice_number = args.invoice_number
+
+    print(f"\n  Ledger diff for invoice: {invoice_number}")
+    print(f"{'─' * 50}")
+    print(f"  This command compares stored invoice total")
+    print(f"  against current ledger state for the same period.")
+    print(f"")
+    print(f"  To use: generate the invoice, note the total,")
+    print(f"  then run this after any ledger amendments.")
+    print(f"{'─' * 50}")
+    print(f"  Invoice number: {invoice_number}")
+    print(f"  Status: requires hosted control plane for full diff")
+    print(f"  Run: ledgrr totals --workspace <id> --period <YYYY-MM>")
+    print(f"  to manually verify ledger totals match your invoice.\n")
+
+
+def cmd_dlq(args):
+    """Inspect the dead-letter queue."""
+    db_path = getattr(args, "db", None)
+    dlq = DeadLetterQueue(db_path)
+    workspace = getattr(args, "workspace", None)
+
+    failures = dlq.get_unresolved(workspace)
+    summary = dlq.get_error_summary()
+
+    print(f"\n  Dead-Letter Queue")
+    print(f"{'─' * 60}")
+
+    if not failures:
+        print(f"  ✓ No unresolved failures")
+    else:
+        print(f"  {len(failures)} unresolved failure(s)\n")
+        print(f"  Error Summary:")
+        for s in summary:
+            print(f"    {s['count']}x {s['error_prefix'][:50]}")
+            print(f"       Last seen: {s['last_seen']}")
+
+        if getattr(args, "verbose", False):
+            print(f"\n  All failures:")
+            for f in failures[:10]:
+                print(f"    [{f['id']}] {f['created_at']}")
+                print(f"         {f['error'][:80]}")
+                print(f"         workspace={f['workspace_id']} user={f['user_id']}")
+
+    print(f"{'─' * 60}\n")
+
+
+def cmd_health(args):
+    """Check ledger health and invariants."""
+    ledger = _get_ledger(args)
+    workspace = args.workspace
+    period = args.period
+
+    print(f"\n  Ledger Health Check")
+    print(f"  Workspace: {workspace} / {period}")
+    print(f"{'─' * 50}")
+
+    totals = ledger.get_total_cost_inr(workspace, period)
+    events = ledger.get_events_for_customer(workspace, period)
+
+    # Verify invariant: sum of events == reported total
+    from decimal import Decimal
+    computed_inr = sum(Decimal(str(e.inr_cost)) for e in events)
+    computed_gst = sum(Decimal(str(e.gst_component)) for e in events)
+    reported_inr = Decimal(str(totals["total_inr_cost"]))
+    reported_gst = Decimal(str(totals["total_gst"]))
+
+    inr_ok = abs(computed_inr - reported_inr) <= Decimal("0.01")
+    gst_ok = abs(computed_gst - reported_gst) <= Decimal("0.01")
+
+    print(f"  Events:    {totals['event_count']}")
+    print(f"  INR cost:  ₹{totals['total_inr_cost']} {'✓' if inr_ok else '✗ DRIFT DETECTED'}")
+    print(f"  GST:       ₹{totals['total_gst']} {'✓' if gst_ok else '✗ DRIFT DETECTED'}")
+    print(f"  Invariant: {'✓ PASS' if inr_ok and gst_ok else '✗ FAIL — ledger drift detected'}")
+    print(f"{'─' * 50}\n")
+
+    if not (inr_ok and gst_ok):
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="ledgrr",
+        description="Ledgrr CLI — financial observability for AI systems",
+    )
+    parser.add_argument("--db", help="Path to ledger SQLite file", default=None)
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # totals
+    p = subparsers.add_parser("totals", help="Show cost totals")
+    p.add_argument("--workspace", required=True)
+    p.add_argument("--period", required=True, help="YYYY-MM")
+
+    # users
+    p = subparsers.add_parser("users", help="Per-user cost breakdown")
+    p.add_argument("--workspace", required=True)
+    p.add_argument("--period", required=True)
+
+    # replay
+    p = subparsers.add_parser("replay", help="Replay events from a date")
+    p.add_argument("--from", dest="from_date", required=True, help="YYYY-MM-DD")
+    p.add_argument("--workspace", required=True)
+
+    # diff
+    p = subparsers.add_parser("diff", help="Diff invoice against ledger")
+    p.add_argument("invoice_number")
+
+    # dlq
+    p = subparsers.add_parser("dlq", help="Inspect dead-letter queue")
+    p.add_argument("--workspace", default=None)
+    p.add_argument("--verbose", action="store_true")
+
+    # health
+    p = subparsers.add_parser("health", help="Check ledger health and invariants")
+    p.add_argument("--workspace", required=True)
+    p.add_argument("--period", required=True)
+
+    args = parser.parse_args()
+
+    commands = {
+        "totals": cmd_totals,
+        "users": cmd_users,
+        "replay": cmd_replay,
+        "diff": cmd_diff,
+        "dlq": cmd_dlq,
+        "health": cmd_health,
+    }
+
+    if args.command not in commands:
+        parser.print_help()
+        sys.exit(1)
+
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()