Metadata-Version: 2.5
Name: springprompt
Version: 0.3.0
Summary: Copies a sample of your app's LLM calls to Spring Prompt, which tests them on other models.
Project-URL: Homepage, https://springprompt.com
Author: Spring Prompt
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# springprompt

Copies a sample of your app's LLM calls to Spring Prompt, which tests them on other models and
tells you where you could be better, faster or cheaper.

## Quick start: npx springprompt init

In your app's folder:

```sh
pip install springprompt
python -m springprompt init        # or: npx springprompt init
```

It opens Spring Prompt in your browser. Sign in, pick or make a project, check the code matches
your terminal and confirm "Connect this computer". The terminal then writes a new key to `.env`
(making sure `.env` is in `.gitignore`), never into your code, prints the two lines to add and
where, and offers to send a test call. Options: `--project <id>` picks the project in advance,
`--url` (or `SPRINGPROMPT_URL`) points at another Spring Prompt, `--no-browser` only prints the
address, and `--yes` asks no questions.

## The two lines

```python
import springprompt
springprompt.init()
```

Set `SPRINGPROMPT_KEY` (from your Spring Prompt set-up page) and that is all. Without a key the
package does nothing at all: nothing is patched and nothing is sent.

Your calls still go straight to the provider. The package keeps a copy of the request and the
answer and sends it from a background thread, so it never changes, slows or breaks a call. If
something goes wrong inside the package three times, it takes itself off and says so once.

Check the set-up:

```sh
python -m springprompt init     # sign in in the browser; the key goes in .env
python -m springprompt test     # sends one made-up call; it shows on your set-up page
python -m springprompt status   # key set or not, the address, which libraries are hooked
```

Python 3.9 or later. No dependencies. MIT licence.

## Options

`springprompt.init(key=None, *, url=None, hosts=(), mask=(), redact=None, env=None, release=None, share=None, debug=False)`

| Option | What it does |
| --- | --- |
| `key` | The ingest key. Default: `SPRINGPROMPT_KEY`. |
| `url` | Where to send. Default: `SPRINGPROMPT_URL`, else `https://springprompt.com`. |
| `hosts` | Extra addresses to watch, such as a LiteLLM proxy: `["llm.internal"]`. |
| `mask` | Any of `"email"`, `"phone"`, `"card"` (13 to 19 digits passing the Luhn check), `"ip"`. |
| `redact` | Your own function, given each body as text, returning it cleaned. If it raises, that call is not sent. |
| `env` | Default: `SPRINGPROMPT_ENV`, else `production`. |
| `release` | Default: `SPRINGPROMPT_RELEASE` or your host's commit variable (Railway, Vercel, Render, Heroku, `GIT_COMMIT`). |
| `share` | Starting share of calls sent after the first 20 of each prompt (default 0.1). Spring Prompt may change it. |
| `debug` | Print what the package is doing on stderr. |

Calling `init()` again does nothing.

Name a prompt so its calls group together, with a block or a decorator (works with `async def`
too):

```python
with springprompt.prompt("ticket-triage"):
    client.chat.completions.create(...)

@springprompt.prompt("ticket-triage")
def triage(ticket): ...
```

Without a name, calls are grouped by the file and function that made them.

## What is sent

For each sampled call: the request body and the answer (the raw stream for streamed answers),
the host and path, the status, how long it took, the file and function that made the call, and
the prompt name if you set one. Also counts of calls seen, errors and calls skipped.

The first 20 calls of each prompt are sent; after that about one in ten.

## What is never sent

- Headers of any kind (so never your provider key), and query strings.
- Calls with images, audio or files in the request, and bodies over 256 KB. These are only
  counted.
- Key-like text in the bodies (OpenAI, Anthropic, Google, GitHub, Slack, AWS keys, JWTs, bearer
  tokens): replaced with `[key removed]` before anything leaves your app.
- Anything your `mask` or `redact` takes out.

## Tools and the prompt cache

Calls that use tools need nothing extra: the tool definitions are in the request and the
model's tool calls are in the answer, and both are sent as they are. Spring Prompt tests the
next step the model takes on other models, with the same tools on offer, and never runs a
tool. A tool that takes an image's address or a file as an argument is not media, and its
calls are sent (since 0.2.0; before, such a call was only counted).

Cost takes your provider's prompt cache into account. The token counts, including how many
were read from the cache, are read from the usage in each answer. A streamed OpenAI answer
only has usage if your app asks for it (`stream_options: {"include_usage": true}`).

## Serverless

The package sends every 5 seconds from a background thread, and again when the process exits.
On AWS Lambda, Cloud Functions and the like the process can freeze before that, so call
`springprompt.flush()` at the end of each handler (it waits up to 2 seconds).
`springprompt.shutdown()` sends what is left and stops watching.

Forked workers (Gunicorn, Celery, multiprocessing) are fine: each child starts with an empty
queue and its own thread.

## Supported

- The OpenAI and Anthropic SDKs, sync and async, streamed or not. The Google Gen AI and
  Mistral SDKs use the same libraries (`httpx` or `httpx2`) and are caught the same way.
- `httpx` and `httpx2` used directly.
- `requests` (streamed answers, `stream=True`, are counted but not copied).

Watched by default: OpenAI, Anthropic, Google Gemini API, OpenRouter, Mistral, DeepSeek, xAI,
Groq, Together, Fireworks, Cerebras and Azure OpenAI (`*.openai.azure.com`).

Not yet supported: `aiohttp`, `urllib`, gRPC.

Not yet tried: LiteLLM, LangChain, Azure OpenAI with its own SDK settings. They use the
libraries above, so they should work; tell us if they do not. AWS Bedrock is out of scope.
