Metadata-Version: 2.5
Name: SimVX-AI
Version: 0.0.0.dev3104
Summary: SimVX's LLM layer: one client for OpenAI-compatible endpoints, a record-and-replay cache, and in-game loops that never stall a frame.
Project-URL: Homepage, https://simvx.com
Project-URL: Documentation, https://simvx.com/docs/ai/index.html
Project-URL: Source, https://git.simvx.com/simvx/simvx
Project-URL: Issues, https://git.simvx.com/simvx/simvx/issues
Project-URL: Changelog, https://git.simvx.com/simvx/simvx/commits/branch/main
Author-email: SimVX <contact@simvx.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: httpx>=0.27
Requires-Dist: simvx-core==0.0.0.dev3104
Description-Content-Type: text/markdown

# SimVX AI

SimVX's LLM layer: one client for any OpenAI-compatible `/chat/completions` endpoint, a
record-and-replay cache for tests, and in-game loops that never stall a frame. Most users want
`simvx`, which includes it.

It works with any OpenAI-compatible server, local (vLLM, llama.cpp, OpenWebUI) or hosted: bring
your own endpoint and key.

> **Pre-alpha.** SimVX publishes development releases only (`0.0.0.devN`) and is under active
> development; the API changes between builds. Once stable versions ship to PyPI, development
> builds continue on pypi.simvx.com.

## Install

```bash
pip install --pre simvx        # the whole engine (recommended)
pip install --pre simvx-ai     # the LLM layer on simvx-core alone
```

Latest development build: add `--extra-index-url https://pypi.simvx.com/`.

## Use

`Bark` runs a model call off the frame thread at most every `period` seconds; `poll` returns the
last good line at once, every frame.

```python
from simvx.ai import Bark, OpenAICompatibleClient

client = OpenAICompatibleClient.from_env()   # SIMVX_LLM_BASE_URL, SIMVX_LLM_API_KEY, SIMVX_LLM_MODEL
bark = Bark(client, persona="a weary night watchman", period=6.0)

def on_update(self, dt):
    self.line = bark.poll(dt, hp=self.hp)
```

`Planner` does the same for a JSON-schema decision; `CachingClient` replays recorded responses.
`AgentSession` lets a model play a running game (observe, send input, watch signals, step), and
`NodeGenerator` turns a one-line description into a validated `Node` subclass.

[Documentation](https://simvx.com/docs/ai/index.html) ·
[Source](https://git.simvx.com/simvx/simvx/src/branch/main/packages/ai) ·
Licence: AGPL-3.0-or-later with [Additional Terms](https://git.simvx.com/simvx/simvx/src/branch/main/LICENSE-ADDENDUM.md),
including the Game-Distribution Exception.
