Metadata-Version: 2.4
Name: cutback
Version: 0.1.0.dev4
Summary: Independent, evidence-aware AI application cost observation and optimization
Project-URL: Homepage, https://github.com/CutbackAI/cutback
Project-URL: Repository, https://github.com/CutbackAI/cutback
Project-URL: Issues, https://github.com/CutbackAI/cutback/issues
Project-URL: Documentation, https://github.com/CutbackAI/cutback/tree/main/docs
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: pathspec<2,>=1
Requires-Dist: pydantic<3,>=2.10.6
Requires-Dist: pyyaml<7,>=6
Requires-Dist: typer<1,>=0.20
Provides-Extra: anthropic
Requires-Dist: anthropic==2.3.0; extra == 'anthropic'
Requires-Dist: httpx<1,>=0.28; extra == 'anthropic'
Requires-Dist: opentelemetry-api<2,>=1.38; extra == 'anthropic'
Provides-Extra: commercial
Requires-Dist: stripe==16.0.0; extra == 'commercial'
Provides-Extra: eval
Requires-Dist: cryptography<51,>=50; extra == 'eval'
Requires-Dist: jsonschema<5,>=4.25; extra == 'eval'
Provides-Extra: identity
Requires-Dist: pyjwt[crypto]==2.15.1; extra == 'identity'
Provides-Extra: instrumentation
Requires-Dist: httpx<1,>=0.28; extra == 'instrumentation'
Requires-Dist: opentelemetry-api<2,>=1.38; extra == 'instrumentation'
Provides-Extra: javascript
Requires-Dist: tree-sitter-javascript==0.25.0; extra == 'javascript'
Requires-Dist: tree-sitter-typescript==0.23.2; extra == 'javascript'
Requires-Dist: tree-sitter==0.26.0; extra == 'javascript'
Provides-Extra: openai
Requires-Dist: httpx<1,>=0.28; extra == 'openai'
Requires-Dist: openai==2.29.0; extra == 'openai'
Requires-Dist: opentelemetry-api<2,>=1.38; extra == 'openai'
Provides-Extra: server
Requires-Dist: alembic<2,>=1.17; extra == 'server'
Requires-Dist: cryptography<51,>=50; extra == 'server'
Requires-Dist: fastapi<1,>=0.120; extra == 'server'
Requires-Dist: jsonschema<5,>=4.25; extra == 'server'
Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'server'
Requires-Dist: sqlalchemy<3,>=2.0.44; extra == 'server'
Requires-Dist: uvicorn<1,>=0.38; extra == 'server'
Provides-Extra: storage
Requires-Dist: boto3>=1.43.118; extra == 'storage'
Description-Content-Type: text/markdown

# Cutback

Find where an AI application spends money. Test cheaper alternatives against its quality requirements. Review the evidence before changing anything.

Cutback is an Apache-2.0 Python tool with an offline scanner and a self-hosted collector, PostgreSQL worker and dashboard. **Pre-alpha: synthetic tests demonstrate the workflow; production behavior and real customer savings are not validated.**

## Start with a working application

The support-desk sample routes tickets by category and priority. Two workflows, ticket triage and escalation, share one native SDK call. It shows why a cheaper configuration that mishandles urgent tickets must be rejected.

You need Python 3.11–3.13 and running Docker Desktop. Install in a fresh virtual environment. The dashboard is already built; no Node setup or provider API key is needed for the sample.

```sh
python -m pip install "cutback[server,openai]==0.1.0.dev4"
cutback demo
```

Wait for `Ready:` in the terminal, then click **Explore sample** in the browser.

| Configuration | Expected sample decision | Why |
|---|---|---|
| Baseline | Reference behavior | Classifies ticket category and priority |
| Compact candidate | Passes sample gates | Preserves synthetic labels with lower modeled fixture cost |
| Unsafe candidate | Not eligible | Loses urgent priorities; a required criterion fails |

**All provider responses in the demo are synthetic.** The scanner, native SDK observation, authenticated HTTP collector, PostgreSQL, encrypted evidence, approvals and worker are real. Fixture prices and latency are not real-model benchmarks, invoices or customer savings. No paid inference occurs.

The sample stays available for exploration while the command runs. Inspect calls, modeled usage, scorecards, failure-first paired cases, immutable label corrections, smoke/pilot/test receipts and a source diff with rollback. Costs distinguish application, evaluation, judge and unknown traffic. Encrypted diffs can be reviewed on the ordinary Changes page. Nothing is applied or deployed. Press Ctrl+C to remove its own temporary database and encrypted artifacts.

![Synthetic support-desk comparison: compact passes and unsafe fails priority](https://raw.githubusercontent.com/CutbackAI/cutback/v0.1.0.dev4/docs/assets/support-desk-decisions.png)

Read [the walkthrough and testing checklist](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/testing-the-sample.md) for every expected result and troubleshooting. This walkthrough targets dev4. Earlier releases have different evidence and review controls.

## Try the offline scanner without Docker

```sh
cutback sample support-desk
cutback scan support-desk
cutback opportunities --target support-desk
```

This copies a standalone native-SDK app and owned synthetic cases. Scanning parses files without executing them or making a network request. It finds source call sites; historical usage, spend and quality remain unknown until measured. Add `--json` for machine-readable scan/opportunity output.

## Use your own application

Start with [application onboarding](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/application-onboarding.md). Keep your dependencies pinned and save findings in that application's ignored `.cutback/` directory. Prepare an instrumentation diff before authorizing its application or deployment.

For runtime observation, connect a scoped ingestion key to your own collector. For optimization, supply permitted examples and explicit quality criteria, review the complete budget, and approve one frozen plan. Metadata is the default; raw content requires a separate active rights policy and encrypted storage. No application name, source or report needs to be published to this repository.

## Define what good means

[Experiment files](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/experiment-files.md) describe named model/prompt variants, required criteria, optional rubric judging, budgets and staged execution. The dashboard exposes scorecards, segments, descriptive paired comparisons and audited encrypted case reads. Lower cost never overrides a required quality failure; synthetic results never establish customer quality.

## What this solves

Use Cutback when you want a reviewable answer to “Can this workflow use a cheaper configuration without failing its declared checks?” It links source discovery, observed usage, frozen quality comparisons and a patch with rollback. It complements your existing tracing system; it does not claim exhaustive discovery, production readiness or universal provider support.

## Explore further

- [Other examples](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/examples/README.md): sync/async/streams, FastAPI, Django, Lambda, workers and Node.
- [Existing OpenTelemetry pipelines](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/otel-ingestion.md): reuse a filtered JSON metadata export without stacking SDK hooks.
- [Provider compatibility](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/providers.md): exact supported SDKs/models and limitations.
- [Evaluation](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/evaluation.md): frozen datasets, independent labels, uncertainty and approval semantics.
- [Deployment](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/deployment.md) and [privacy](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/security-and-privacy.md): customer-owned PostgreSQL, scoped credentials, retention and encrypted payloads.
- [Agent workflows](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/agent-integration.md): portable instructions for supported agent clients.
- [Architecture](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/architecture.md), [contributing](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/CONTRIBUTING.md) and [implementation progress](https://github.com/CutbackAI/cutback/blob/v0.1.0.dev4/docs/progress.md): internals, executed acceptance and outstanding external gates.

Optional identity, billing, storage, scheduling, routing and training are documented separately. They are not prerequisites for understanding the sample. JavaScript/TypeScript scanning and native Node observation are optional; npm publication is separate. No managed cloud service is operated by this repository.
