Metadata-Version: 2.4
Name: lutflow
Version: 0.2.0
Summary: AI Cost Intelligence for LLM inference — track and enforce your LLM spend in-process, across providers.
Project-URL: Homepage, https://lutflow.dev
Project-URL: Documentation, https://pypi.org/project/lutflow/
Author-email: "Lutflow Inc." <oscar@lutflow.com>
License: Business Source License 1.1
        
        Parameters
        
        Licensor:             Lutflow Inc.
        Licensed Work:        Lutflow SDK
                              The Licensed Work is (c) 2026 Lutflow Inc.
        Additional Use Grant: You may make use of the Licensed Work, provided that
                              you do not use the Licensed Work for a GPU Cost Management
                              Service.
        
                              A "GPU Cost Management Service" is a commercial offering
                              that allows third parties to access the functionality of
                              the Licensed Work by performing any of the following:
                              (a) offering budget enforcement, cost tracking, or kill-path
                                  functionality for GPU or AI inference workloads as a
                                  managed service;
                              (b) offering the Licensed Work to third parties as a
                                  commercial cloud service, hosted service, or
                                  software-as-a-service.
        
                              For clarity, the following uses are permitted:
                              - Internal use within your organization
                              - Development, testing, and evaluation
                              - Non-commercial and educational use
                              - Integration into your own products that do not compete
                                with Lutflow's commercial offerings
        
        Change Date:          March 29, 2030
        Change License:       Apache License, Version 2.0
        
        For information about alternative licensing arrangements for the Licensed Work,
        please contact: licensing@lutflow.com
        
        -----------------------------------------------------------------------------
        
        Business Source License 1.1
        
        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
        "Business Source License" is a trademark of MariaDB Corporation Ab.
        
        Terms
        
        The Licensor hereby grants you the right to copy, modify, create derivative
        works, redistribute, and make non-production use of the Licensed Work. The
        Licensor may make an Additional Use Grant, above, permitting limited
        production use.
        
        Effective on the Change Date, or the fourth anniversary of the first publicly
        available distribution of a specific version of the Licensed Work under this
        License, whichever comes first, the Licensor hereby grants you rights under
        the terms of the Change License, and the rights granted in the paragraph
        above terminate.
        
        If your use of the Licensed Work does not comply with the requirements
        currently in effect as described in this License, you must purchase a
        commercial license from the Licensor, its affiliated entities, or authorized
        resellers, or you must refrain from using the Licensed Work.
        
        All copies of the original and modified Licensed Work, and derivative works
        of the Licensed Work, are subject to this License. This License applies
        separately for each version of the Licensed Work and the Change Date may vary
        for each version of the Licensed Work released by Licensor.
        
        You must conspicuously display this License on each original or modified copy
        of the Licensed Work. If you receive the Licensed Work in original or
        modified form from a third party, the terms and conditions set forth in this
        License apply to your use of that work.
        
        Any use of the Licensed Work in violation of this License will automatically
        terminate your rights under this License for the current and all other
        versions of the Licensed Work.
        
        This License does not grant you any right in any trademark or logo of
        Licensor or its affiliates (provided that you may use a trademark or logo of
        Licensor as expressly required by this License).
        
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
        TITLE.
        
        MariaDB hereby grants you permission to use this License's text to license
        your works, and to refer to it using the trademark "Business Source License",
        as long as you comply with the Covenants of Licensor below.
        
        Covenants of Licensor
        
        In consideration of the right to use this License's text and the "Business
        Source License" name and trademark, Licensor covenants to MariaDB, and to all
        other recipients of the licensed work to be provided by Licensor:
        
        1. To specify as the Change License the GPL Version 2.0 or any later version,
           or a license that is compatible with GPL Version 2.0 or a later version,
           where "compatible" means that software provided under the Change License can
           be included in a program with software provided under GPL Version 2.0 or a
           later version. Licensor may specify additional Change Licenses without
           limitation.
        
        2. To either: (a) specify an additional grant of rights to use that does not
           impose any additional restriction on the right granted in this License, as
           the Additional Use Grant; or (b) insert the text "None".
        
        3. To specify a Change Date.
        
        4. Not to modify this License in any other way.
License-File: LICENSE
Keywords: ai,anthropic,budget-tracking,cost-management,energy-efficiency,finops,gpu,llm,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: httpx<1.0.0,>=0.25.0
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: tiktoken<1.0.0,>=0.5.0
Provides-Extra: all
Requires-Dist: anthropic<2.0.0,>=1.0.0; extra == 'all'
Requires-Dist: google-generativeai<1.0.0,>=0.8.0; extra == 'all'
Requires-Dist: openai<2.0.0,>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic<2.0.0,>=1.0.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-generativeai<1.0.0,>=0.8.0; extra == 'gemini'
Provides-Extra: openai
Requires-Dist: openai<2.0.0,>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# Lutflow — AI Cost Intelligence for LLM inference

The Lutflow SDK gives developers a first, honest handle on **what LLM inference
costs** — and how to keep it in check. Track and enforce your provider spend
**in-process** (OpenAI · Anthropic · Gemini), with budget strategies that fit
your workflow.

```bash
pip install lutflow
```

Offline-first — no account, no backend needed to start.

---

## What this SDK is today

| Capability | Status | Notes |
|-----------|--------|-------|
| **In-process budget enforcement** | ✅ Ships, real | Tracks token/GPU-time spend in your process and, on breach, `raise`s, warns, runs a callback, or `SIGKILL`s the current process. |
| **Provider wrappers** | ✅ Ships, real | OpenAI, Anthropic, Google Gemini — wrap the client, spend is metered per call. |
| **Pricing tables** | ✅ Ships, real | Token and GPU-hour pricing with per-model overrides. |
| **`lutflow measure`** | ✅ Ships, real | Small offline utility: cost & energy metrics from a telemetry export. Read-only, no network. |

> Budget enforcement acts only on the **current Python process** (raise / warn
> / callback / `SIGKILL` of `os.getpid()`) — it is not cluster-level workload
> termination.

*The connected Lutflow platform — fleet-wide cost intelligence — is in private
development.*

---

## In-process budget enforcement

Wrap your provider client; Lutflow meters every call and enforces the limit
locally. This runs entirely in your process — no account, no network.

```python
from lutflow import Client, BudgetStrategy
import openai

client = Client(
    tenant_id="acme",
    budget_usd=10.00,
    on_budget_exceeded=BudgetStrategy.RAISE_ERROR,
)
wrapped = client.wrap(openai.OpenAI())
response = wrapped.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(f"Spent:     ${client.accumulated_cost_usd:.4f}")
print(f"Remaining: ${client.remaining_budget_usd:.4f}")
```

When the budget is exceeded, the configured strategy fires **in this process**:

| Strategy | Behavior (in-process) |
|----------|-----------------------|
| `RAISE_ERROR` | Raises `BudgetExceededError` (default) |
| `WARN_ONLY` | Logs a warning, continues |
| `CALLBACK` | Calls a function you provide |
| `SELF_KILL` | Sends `SIGKILL` to the current process (`os.getpid()`) |

A context-manager form is also available:

```python
from lutflow import budget_session

with budget_session(budget_usd=0.50, tenant_id="acme") as session:
    wrapped = session.wrap(openai.OpenAI())
    ...
```

### GPU-time pricing (self-hosted models)

```python
from lutflow import Client, PricingMode

client = Client(
    tenant_id="acme",
    budget_usd=5.00,
    pricing_mode=PricingMode.GPU_TIME,
    gpu_type="nvidia-l4",
)
client.start_gpu_timer()
# ... run inference ...
cost = client.stop_gpu_timer()
```

### `lutflow measure` — cost & energy metrics from a telemetry export

A small offline utility: point it at a GPU telemetry export and get a
per-concurrency breakdown of cost and energy per token. Read-only, no network.

```bash
lutflow measure --from-telemetry telemetry.jsonl --price-per-hr 0.85
```

---

## Installation

```bash
pip install lutflow            # Core + CLI (measure + in-process enforcement)
pip install lutflow[openai]    # + OpenAI wrapper
pip install lutflow[anthropic] # + Anthropic wrapper
pip install lutflow[gemini]    # + Google Gemini wrapper
pip install lutflow[all]       # All providers
```

Supported providers: **OpenAI**, **Anthropic**, **Google Gemini**, and
**self-hosted** (vLLM / TGI / BentoML via GPU-time pricing).

---

## Links

- **Website**: [lutflow.dev](https://lutflow.dev)
- **PyPI**: [pypi.org/project/lutflow](https://pypi.org/project/lutflow/)
- **Support**: <oscarmatiasg@lutflow.com>

## License

Business Source License 1.1 (BSL 1.1)

- **Free for**: internal use, development, testing, evaluation, non-commercial use
- **Commercial license required for**: offering GPU cost management as a service
- **Change Date**: March 29, 2030 (converts to Apache 2.0)

See [LICENSE](LICENSE) for full terms. For commercial licensing: licensing@lutflow.com
