foilengine 0.3.0

Python SDK for the Foil Engine NPC API

Foil Engine Python SDK

Python SDK for the Foil Engine NPC API. Add AI-powered NPC conversations to your game or application.

Installation

pip install foilengine

Quick Start

from foilengine import FoilEngineClient

client = FoilEngineClient(
    api_key="pk_live_...",
    llm_api_key="sk-...",   # your LLM provider API key
    llm_model="gpt-4o",     # any LiteLLM-supported model
)

# Discover your personas
personas = client.personas.list()

# Initialize a session
session = client.chat.init_session(
    persona_id=personas[0].id,
    user_session_id="player-001",
    player_name="Alex",
    player_gender="non-binary",
)
print(session.message)  # NPC's greeting

# Send a message
response = client.chat.send_message(
    persona_id=personas[0].id,
    message="What do you recommend?",
    user_session_id="player-001",
)
print(response.message)       # NPC's reply
print(response.current_state) # State machine state
print(response.score)         # Session score

Async Support

from foilengine import AsyncFoilEngineClient

async with AsyncFoilEngineClient(api_key="pk_live_...", llm_api_key="sk-...", llm_model="gpt-4o") as client:
    personas = await client.personas.list_async()
    response = await client.chat.send_message_async(
        persona_id=personas[0].id,
        message="Hello!",
        user_session_id="player-001",
    )

Configuration

client = FoilEngineClient(
    api_key="pk_live_...",              # required
    llm_api_key="sk-...",              # required – your LLM provider API key
    llm_model="gpt-4o",               # optional – default LLM model
    base_url="http://localhost:8000",   # default: https://api.foilengine.io
    timeout=30.0,                       # default: 30s
    max_retries=3,                      # default: 3
)

LLM Configuration (BYOK)

SDK chat endpoints require your own LLM API key. Foil Engine uses LiteLLM under the hood, so any supported provider and model string works.

# Use OpenAI
client = FoilEngineClient(
    api_key="pk_live_...",
    llm_api_key="sk-...",
    llm_model="gpt-4o",
)

# Use Anthropic
client = FoilEngineClient(
    api_key="pk_live_...",
    llm_api_key="sk-ant-...",
    llm_model="anthropic/claude-sonnet-4-20250514",
)

# Override models per pipeline step
client = FoilEngineClient(
    api_key="pk_live_...",
    llm_api_key="sk-...",
    llm_model="gpt-4o",
    llm_eval_model="gpt-4o-mini",          # cheaper model for evaluation
    llm_response_model="gpt-4o",           # main model for NPC responses
    llm_summarization_model="gpt-4o-mini", # cheaper model for summaries
)

Documentation

Full documentation at foilengine.io/docs/sdk/python

License

MIT