Freeplay Python SDK

The official Python SDK for Freeplay
The ops platform for enterprise AI engineering teams

Docs • Quick Start • SDK Setup • API Reference • Changelog • Contributing

Overview

Freeplay is the only platform your team needs to manage the end-to-end AI application development lifecycle. It provides an integrated workflow for improving your AI agents and other generative AI products. Engineers, data scientists, product managers, designers, and subject matter experts can all review production logs, curate datasets, experiment with changes, create and run evaluations, and deploy updates.

Use this SDK to integrate with Freeplay's core capabilities:

Observability
- Sessions — group related interactions together, e.g. for multi-turn chat or complex agent interactions
- Traces — track multi-step agent workflows within sessions
- Completions — record LLM interactions for observability and debugging
- Customer Feedback — append user feedback and events to traces and completions
Prompts — version, format, and fetch prompt templates across environments
Test Runs — execute evaluation runs against prompts and datasets

Requirements

Python 3.10 or higher
A Freeplay account + API key

Installation

pip install freeplay

Quick Start

import os
from freeplay import Freeplay, RecordPayload
from openai import OpenAI

fp_client = Freeplay(
    freeplay_api_key=os.environ["FREEPLAY_API_KEY"],
)
openai_client = OpenAI()

project_id = os.environ["FREEPLAY_PROJECT_ID"]

# Fetch a prompt from Freeplay
formatted_prompt = fp_client.prompts.get_formatted(
    project_id=project_id,
    template_name="my-prompt",
    environment="prod",
    variables={"user_input": "Hello, world!"},
)

# Call your LLM provider with formatted_prompt.llm_prompt
response = openai_client.chat.completions.create(
    model=formatted_prompt.prompt_info.model,
    messages=formatted_prompt.llm_prompt,
)

# Record the interaction for observability
fp_client.recordings.create(
    RecordPayload(
        project_id=project_id,
        all_messages=formatted_prompt.all_messages({
            "role": "assistant",
            "content": response.choices[0].message.content,
        }),
    )
)

See the SDK Setup guide for complete examples.

Configuration

Environment variables

export FREEPLAY_API_KEY="fp_..."
export FREEPLAY_PROJECT_ID="xy..."
# Optional: override if using a custom domain / private deployment
export FREEPLAY_API_BASE="https://app.freeplay.ai/api"

API base URL
Default: https://app.freeplay.ai/api

Custom domain/private deployment: https://<your-domain>/api

Versioning

This SDK follows Semantic Versioning (SemVer): MAJOR.MINOR.PATCH.

PATCH: bug fixes
MINOR: backward-compatible features
MAJOR: breaking changes

Before upgrading major versions, review the changelog.

Support

Docs: https://docs.freeplay.ai
Issues: https://github.com/freeplayai/freeplay-python/issues
Security: security@freeplay.ai

Contributing

See CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE.

Metadata

Release files for freeplay 0.6.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 freeplay 0.6.0
File	Size	Uploaded
freeplay-0.6.0.tar.gz	840.9 kB	Apr 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for freeplay 0.6.0
File	Interpreter	ABI	Platform	Reset
freeplay-0.6.0-py3-none-any.whl 43.2 kB Apr 21, 2026	Python 3	none	any	Details

Total release size: 884.1 kB

Release files / freeplay-0.6.0.tar.gz

Download URL	freeplay-0.6.0.tar.gz
Size	840.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`279360e444aaf8ee2dba44bdf7e5f65ec833df7e0f71347078555eada0736646`
BLAKE2b-256 checksum How to use checksums	`c6abb778a3d45ab20ec5f5aaed1ff6682356efb2990a181b2bee5f8813f87e22`
Upload date	Apr 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / freeplay-0.6.0-py3-none-any.whl

Download URL	freeplay-0.6.0-py3-none-any.whl
Size	43.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c5bf0bfef15c2924669ec21a429a94d07b8da903ebb1dbbe2f62784694dd8d02`
BLAKE2b-256 checksum How to use checksums	`4859b8561fe801539a0261ae3e4b12c0f557d1d2dea0f56af2430283134cac06`
Upload date	Apr 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`