Metadata-Version: 2.4
Name: foilengine
Version: 0.2.1
Summary: Python SDK for the Foil Engine NPC API
Project-URL: Homepage, https://foilengine.io
Project-URL: Documentation, https://foilengine.io/docs/sdk/python
Project-URL: Repository, https://github.com/py1218/foilengine-python
Author: Foil Engine
License-Expression: MIT
License-File: LICENSE
Keywords: ai,chatbot,foilengine,game,npc,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# Foil Engine Python SDK

Python SDK for the [Foil Engine](https://foilengine.io) NPC API. Add AI-powered NPC conversations to your game or application.

## Installation

```bash
pip install foilengine
```

## Quick Start

```python
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

```python
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

```python
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](https://docs.litellm.ai/docs/providers) under the hood, so any supported provider and model string works.

```python
# 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](https://foilengine.io/docs/sdk/python)

## License

MIT
