Metadata-Version: 2.4
Name: foilengine
Version: 0.1.0
Summary: Python SDK for the Foil Engine NPC API
Project-URL: Homepage, https://foilengine.com
Project-URL: Documentation, https://foilengine.com/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.com) 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_...")

# 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_...") 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
    base_url="http://localhost:8000",   # default: https://api.foilengine.com
    timeout=30.0,                       # default: 30s
    max_retries=3,                      # default: 3
)
```

## Documentation

Full documentation at [foilengine.com/docs/sdk/python](https://foilengine.com/docs/sdk/python)

## License

MIT
