Installing and upgrading

What you'll learn

• which Python versions work;
• how to install the SDK in its own environment;
• how to check the version you have;
• what the optional extras add;
• how to upgrade without surprises;
• what the SDK saves on your disk.

Which Python versions work

Python 3.9 to 3.13. The SDK needs two other packages, requests and urllib3, and pip installs them for you.

A newer Python, such as 3.14, can install the SDK too, but the SDK is not tested there yet. If something fails on a newer Python, use one from the list.

To see which Python you have, type python3 --version on a Mac or Linux, or py --version on Windows. On Windows, typing python when Python is not installed may open the Microsoft Store instead.

Step 1: Install in its own environment

Give each project its own Python environment. Then the packages of one project cannot clash with another's. Python calls this a virtual environment. Many systems also refuse to install packages into their own Python, with the message externally-managed-environment, and a virtual environment avoids that.

On a Mac or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install foxy-audit

On Windows, in PowerShell:

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install foxy-audit

If PowerShell says that running scripts is disabled on this system, type Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass, then the activate line again. That change lasts only for this terminal window.

After this, python and foxy in that terminal use the new environment. Run the activate line again each time you open a new terminal.

Step 2: Check which version you have

python -c "import foxy_audit; print(foxy_audit.__version__)"

What you should see:

1.18.0

python -m pip show foxy-audit tells you the same, and where the package is installed.

Step 3: Add the optional extras, if you need them

Deeper personal-data checks. This adds a language model that finds names, places and dates. It is large, and it runs on your machine:

python -m pip install "foxy-audit[pii]"
python -m spacy download en_core_web_lg

foxy doctor tells you whether it loaded. Policies and rules explains what it changes.

Test tools. The [test] extra installs two tools for testing, pytest and httpx:

python -m pip install "foxy-audit[test]"

It does not add the SDK's own tests, which are not in the package. Most people do not need it.

Step 4: Upgrade

python -m pip install --upgrade foxy-audit

Before you upgrade a program that uses block or redact mode, know this: a new version can add rules. A prompt that passed before may be stopped after. To upgrade safely:

1. Read what changed in the new version. The release notes are in the package's description on PyPI, at https://pypi.org/project/foxy-audit/, with a section for each version. The Release history tab lists only the versions and their dates.
2. Upgrade a test copy of your program first.
3. Run your usual prompts through the new version with foxy check, or run the test copy in block mode, and see what it would stop. observe mode cannot show you this, because it does not check prompts before the call.
4. Then upgrade the real program.

Version 1.18.0 also checks, in your code, a few values the backend refuses. Before, such a value was sent, refused, and sent again, and its records never arrived. Now @audit(agent=...), FoxyClient(client_id=...) and log_interaction raise ValueError for an agent, a client id, a tag or an event type the backend would refuse, and FoxyClient(audit_required=True) raises it when no API key is set. Run your program once after you upgrade to see whether any of yours needs changing. The wire format lists what the backend accepts.

Version 1.18.0 also counts a record as sent only when the backend's own answer names it. Before, any answer that meant success counted, even one from a proxy or a gateway in front of the backend, and the record was removed from the spool. Now such an answer leaves the records in the spool to be sent again, and foxy doctor shows NotAcknowledged as the last delivery error.

Version 1.18.0 also changes the key your hashes are made with. Before, with no key set, it was your API key. Now the SDK makes a key of its own, in commitment.key next to the spool, and Foxy Audit never sees it. Back that file up. Records made before the upgrade are not changed. They still check out with your API key, and foxy explain tries both keys. In a container, set FOXY_COMMITMENT_KEY from your secret store.

A record on which a rule fired names the ruleset that checked it, so records made before and after the upgrade can each be proved against their own rules. A record on which nothing fired names no ruleset.

Upgrading programs that share a spool

If several programs on one machine share one spool file, upgrade them all at the same time. Version 1.18.0 stopped keeping API keys in the spool, and an older program cannot send the records a newer one has changed. It keeps trying until it is upgraded. The records are kept, never lost.

Two notices are normal after the upgrade. foxy doctor prints them as lines that start with an arrow, and they do not change its exit code:

• for up to an hour after a 1.18.0 program first opens an older spool, a notice says the file may still hold old API keys in its unused space, until it is cleaned. Your program's background thread cleans it, and foxy spool compact does it at once;
• on a shared spool, foxy doctor run with one program's key shows the other programs' waiting records as a notice. They are kept for the key they were made with.

Going back to a version before 1.18.0 is not supported once a newer version has used the spool.

What the SDK saves on your disk

None of these files holds your prompts or your model's answers.

The SDK limits who can open the spool file, the two helper files SQLite keeps beside it, the key file and the salt file:

• on Linux and macOS, to its owner (file mode 0600);
• on Windows, to your own account;
• on Windows, when a program running as administrator made the file, to the Administrators group and the account the program runs as;
• a file the SDK did not make is left as it is.

The spool and delivery gives the details, including what happens after a restart.

If it goes wrong