Skip to main content

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:

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

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:

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):

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.

Metadata

Release files for springprompt 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for springprompt 0.3.0
File Size Uploaded Provenance Actions
springprompt-0.3.0.tar.gz 34.7 kB Without provenance Details for springprompt-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for springprompt 0.3.0
File Interpreter ABI Platform Actions
springprompt-0.3.0-py3-none-any.whl Python 3 none any Details for springprompt-0.3.0-py3-none-any.whl

Total release size: 60.5 kB

Release files / springprompt-0.3.0.tar.gz

Download URL springprompt-0.3.0.tar.gz
Size 34.7 kB
Tags Source
SHA-256 checksum
How to use checksums
e9c76bb19edd60808f18b3a6dac050ec02576bf9b6d151e2ee15c502af89db3d
BLAKE2b-256 checksum
How to use checksums
0f957a5891d7578d05966394bdebcbd8b2a2f01233936ec98940f77b28e6eebd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / springprompt-0.3.0-py3-none-any.whl

Download URL springprompt-0.3.0-py3-none-any.whl
Size 25.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28e176cec66fd972a24e235e836ad19d9423ef89ef3e5afbe9f88693876f7e44
BLAKE2b-256 checksum
How to use checksums
9642532d5a235e568db64f7b23e1b2b050af1f21fe1ef98d6934eecf6c9bd83a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for springprompt 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page