Metadata-Version: 2.4
Name: sovereign-engine
Version: 1.0.4
Summary: Procedural Game Engine powered by IntentShield and LogicShield (BSL 1.1)
Home-page: https://github.com/sovereign-shield/sovereign-engine
Author: SovereignShield
Author-email: support@sovereignshield.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

ï»¿# Sovereign Engine

The Zero-Trust Procedural Game Engine. Built securely on the **IntentShield** and **LogicShield** architectures. 

Sovereign Engine allows game developers to seamlessly integrate LLMs (Large Language Models) into their games to generate procedural dialogue, dynamic quests, and complex NPC interactions while absolutely guaranteeing that the AI's output mathematically adheres to your game's rules.

## Installation

```bash
pip install sovereign-engine
```

## Features
- **Deterministic Validation:** The `LogicShield` backend forces the LLM to output perfect JSON that maps exactly to your defined game state parameters.
- **Action Gatekeeper:** A deeply integrated, ultra-fast `IntentShield` system intercepts the AI's intended actions, instantly rejecting anything that isn't functionally possible in your game.
- **Model Agnostic:** Plug in ANY language model (Ollama, Gemini, Local Llama3, OpenAI) via a custom callback function.

## Quick Start

```python
from sovereign_engine.engine import ProceduralDialogueEngine

# The engine routes through OpenRouter automatically by default
engine = ProceduralDialogueEngine(api_key="sk-or-your-developer-key")

# Pass the player's current environment directly to the engine
scene = engine.generate_node(
    player_state={"level": 5, "inventory": ["Iron Sword", "Shield"]},
    recent_history=["You enter a dark cavern and hear a low growl."],
    player_action="I walk forward with my shield raised."
)

print(scene)
```

## Connecting Custom LLMs (Ollama, Gemini, etc.)
You do not have to use OpenRouter. You can pass a custom Python callback function into `llm_provider` to use local open-source models (like Llama3 via Ollama) or other cloud providers exactly as you need to.

```python
import requests
from sovereign_engine.engine import ProceduralDialogueEngine

def local_ollama_call(prompt: str) -> str:
    # Send the engine's prompt to your local un-censored model!
    res = requests.post(
        "http://localhost:11434/api/generate", 
        json={"model": "llama3", "prompt": prompt, "stream": False}
    )
    return res.json()["response"]

# Inject your local LLM into the engine logic!
engine = ProceduralDialogueEngine(llm_provider=local_ollama_call)

scene = engine.generate_node(...)
```

## Customizing Rules (LogicShield) & Actions (IntentShield)

You can easily expand the engine to enforce your own custom mechanics mathematically, or allow new verbs for the AI to take (like `CRAFT` or `STEAL`).

```python
from sovereign_engine.logicshield.rules import Rule

my_rules = [
    # Force the LLM to include a gold reward that is less than max_loot
    Rule.less_than("gold_dropped", "max_loot")
]

engine = ProceduralDialogueEngine(
    llm_provider=local_ollama_call, 
    custom_actions=["STEAL", "CRAFT", "PERSUADE"], 
    custom_rules=my_rules
)
```

## License
This project is licensed under the **Business Source License 1.1 (BSL 1.1)**. 
For production or commercial use, you must obtain a separate commercial license from SovereignShield. 
