# freeplay
> Node.js/Typescript SDK for Freeplay AI
Latest version **0.7.4** (published 2026-04-24) · Apache-2.0 license · 0 weekly downloads
## Install
```sh
npm install freeplay
pnpm add freeplay
yarn add freeplay
bun add freeplay
```
## Health
**Score 55/100 (C)** — status: stable.
Positive: esm support; no vulnerabilities; has provenance.
Warnings: low downloads; no types; pre 1.0.
## Facts
| | |
|---|---|
| Version | 0.7.4 |
| Published | 2026-04-24 |
| First published | 2023-07-14 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 315.9 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Freeplay |
| Maintainers | aleckhoury |
## Links
- npm: https://www.npmjs.com/package/freeplay
- Repository: https://github.com/freeplayai/freeplay-node
- Homepage: https://github.com/freeplayai/freeplay-node#readme
- Issues: https://github.com/freeplayai/freeplay-node/issues
- npm.io page: https://npm.io/package/freeplay
## Dependencies (7)
- [axios](https://npm.io/package/axios.md) ^1.8.2
- [dotenv](https://npm.io/package/dotenv.md) 16.6.1
- [openai](https://npm.io/package/openai.md) ^4.83.0
- [encoding](https://npm.io/package/encoding.md) ^0.1.13
- [mustache](https://npm.io/package/mustache.md) ^4.1.0
- [@anthropic-ai/sdk](https://npm.io/package/@anthropic-ai/sdk.md) ^0.82.0
- [@aws-sdk/client-bedrock-runtime](https://npm.io/package/@aws-sdk/client-bedrock-runtime.md) ^3.901.0
## Recent versions
- 0.7.4 (latest) — 2026-04-24
- 0.5.2-alpha.2 (alpha) — 2025-12-31
- 0.7.3 — 2026-04-17
- 0.6.3 — 2026-03-24
- 0.6.2 — 2026-03-16
- 0.6.1 — 2026-03-11
- 0.6.0 — 2026-03-10
- 0.5.5 — 2026-02-19
- 0.5.3 — 2025-12-31
- 0.5.2-alpha.1 — 2025-10-09
- 0.5.1 — 2025-10-07
- 0.5.1-alpha.1 — 2025-09-11
- 0.5.0 — 2025-08-28
- 0.5.0-alpha.3 — 2025-08-25
- 0.5.0-alpha.2 — 2025-08-07
- … 71 more at https://npm.io/package/freeplay/versions
## README
Freeplay Node SDK
The official Node/TypeScript 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**](https://docs.freeplay.ai/freeplay-sdk/sessions) — group related interactions together, e.g. for multi-turn chat or complex agent interactions
- [**Traces**](https://docs.freeplay.ai/freeplay-sdk/traces) — track multi-step agent workflows within sessions
- [**Completions**](https://docs.freeplay.ai/freeplay-sdk/recording-completions) — record LLM interactions for observability and debugging
- [**Customer Feedback**](https://docs.freeplay.ai/freeplay-sdk/customer-feedback) — append user feedback and events to traces and completions
- [**Prompts**](https://docs.freeplay.ai/freeplay-sdk/prompts) — version, format, and fetch prompt templates across environments
- [**Test Runs**](https://docs.freeplay.ai/freeplay-sdk/test-runs) — execute evaluation runs against prompts and datasets
## Requirements
- Node.js 18 or higher
- A Freeplay account + API key
## Installation
```bash
npm install freeplay
```
## Quick Start
```typescript
import Freeplay from "freeplay";
import OpenAI from "openai";
const fpClient = new Freeplay({
freeplayApiKey: process.env.FREEPLAY_API_KEY,
});
const openai = new OpenAI();
const projectId = process.env.FREEPLAY_PROJECT_ID;
// Fetch a prompt from Freeplay
const formattedPrompt = await fpClient.prompts.getFormatted({
projectId,
templateName: "my-prompt",
environment: "prod",
variables: { user_input: "Hello, world!" },
});
// Call your LLM provider with formattedPrompt.llmPrompt
const response = await openai.chat.completions.create({
model: formattedPrompt.promptInfo.model,
messages: formattedPrompt.llmPrompt,
});
// Record the interaction for observability
await fpClient.recordings.create({
projectId,
allMessages: formattedPrompt.allMessages({
role: "assistant",
content: response.choices[0].message.content,
}),
});
```
See the [SDK Setup guide](https://docs.freeplay.ai/freeplay-sdk/setup) for complete examples.
## Configuration
### Environment variables
```bash
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:///api`
**Merge Semantics**: New keys overwrite existing keys, preserving unmentioned keys.
### Tool Schemas
The SDK supports multiple tool schema formats for different LLM providers. Tool schemas are passed as plain objects in the provider's native format.
#### GenAI/Vertex AI Format
GenAI uses a unique structure where a single tool contains multiple function declarations:
```typescript
// Tool schema as a plain object (GenAI/Vertex format)
const toolSchema = [
{
functionDeclarations: [
{
name: "get_weather",
description: "Get the current weather for a location",
parameters: {
type: "object",
properties: {
location: { type: "string", description: "City name" },
units: {
type: "string",
enum: ["celsius", "fahrenheit"],
},
},
required: ["location"],
},
},
// Multiple functions can be in a single tool (GenAI-specific)
{
name: "get_news",
description: "Get latest news",
parameters: {
type: "object",
properties: {
topic: { type: "string" },
},
required: ["topic"],
},
},
],
},
];
await freeplay.recordings.create({
projectId,
allMessages: [...],
toolSchema,
callInfo: { provider: "vertex", model: "gemini-2.0-flash" },
});
```
#### OpenAI Format
```typescript
const toolSchema = [
{
type: "function",
function: {
name: "get_weather",
description: "Get weather information",
parameters: {
type: "object",
properties: {
location: { type: "string" },
},
required: ["location"],
},
},
},
];
```
#### Anthropic Format
```typescript
const toolSchema = [
{
name: "get_weather",
description: "Get weather information",
input_schema: {
type: "object",
properties: {
location: { type: "string" },
},
required: ["location"],
},
},
];
```
**Note**: All formats are backward compatible. The backend automatically normalizes tool schemas regardless of format. Tool schemas should be passed as-is from the provider SDK (e.g., `@google/generative-ai`, `openai`, `@anthropic-ai/sdk`), similar to how messages are handled.
See the [Freeplay Docs](https://docs.freeplay.ai) for more usage examples and the API reference.
## Documentation
For comprehensive documentation and examples, visit **[docs.freeplay.ai](https://docs.freeplay.ai)**.
## 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.
### Building and Testing
```bash
# Install dependencies
npm run safe-install
```
## Support
- **Docs**: https://docs.freeplay.ai
- **Issues**: https://github.com/freeplayai/freeplay-node/issues
- **Security**: security@freeplay.ai
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
### Interactive REPL
The SDK includes an interactive REPL for quick testing and development:
```bash
# 1. Create .env file (copy from .env.example)
cp .env.example .env
# Edit .env with your API keys
# 2. Start REPL
# Production mode (default) - connects to app.freeplay.ai
npm run repl
# Local development mode - connects to localhost:8000 with SSL bypass
npm run repl -- --local
```
The REPL provides:
- Pre-initialized `client` (Freeplay instance)
- Environment variables: `projectId`, `sessionId`, `datasetId`, `apiBase`
- Tab completion and syntax highlighting
Example REPL usage:
```javascript
freeplay> await client.recordings.create({
projectId,
allMessages: [
{ role: 'user', content: 'Hello!' },
{ role: 'assistant', content: 'Hi there!' }
],
callInfo: { provider: 'openai', model: 'gpt-4' }
});
```
See [REPL.md](REPL.md) for detailed documentation.
## License
Apache-2.0 — see [LICENSE](LICENSE).
---
_Source: https://npm.io/package/freeplay · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._