Metadata-Version: 2.4
Name: ghocentric-ghost-engine
Version: 0.2.0
Summary: Ghost cognitive engine
Author: Shane Heckathorn
License: MIT
Keywords: ai,engine,cognition,simulation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

ghocentric-ghost-engine

A lightweight, deterministic internal state engine for experimenting with persistent state, temporal dynamics, and emergent behavior in interactive systems.

Ghost is NOT a language model and NOT a decision-maker. It is a minimal, stateful core designed to accumulate interaction signals over time and expose them in a clean, predictable, and serialization-safe way.

This project is intentionally focused on architecture and correctness first. Surface features, integrations, and higher-level reasoning systems are expected to be layered on top of the core in later versions.


INSTALLATION

pip install ghocentric-ghost-engine


BASIC USAGE

from ghost.engine import GhostEngine

engine = GhostEngine()

engine.step({
    "source": "npc_engine",
    "intent": "threat",
    "actor": "player",
    "target": "guard",
    "intensity": 0.5,
})

state = engine.state()
print(state["npc"]["threat_level"])

Ghost mutates state only via explicit step() calls.  
All public-facing state is exposed as dictionaries and is safe to serialize.


CORE DESIGN PRINCIPLES

• Deterministic, persistent state core  
• Explicit state transitions via step()  
• No hidden execution or side effects  
• Public API remains dict-based and serialization-safe  
• Internal typed representations may exist but never leak  
• Designed to be expanded around a stable core, not bloated prematurely  


Ghost does NOT:

• Choose actions  
• Generate dialogue  
• Interpret semantics  
• Store memory implicitly  

Those behaviors belong to external systems that consume Ghost’s state.


STABILITY & GUARANTEES (v0.2.0)

Ghost Engine v0.2.0 establishes the first fully functional deterministic interaction core.

The engine now guarantees:

• Deterministic runtime behavior (same inputs → same outputs)  
• Explicit, bounded state mutation per step  
• Actor state updates across interactions  
• Pairwise relationship mutation with symmetric consistency  
• Bounded cascade propagation across interaction networks  
• Global tension tracking across the system  
• Full JSON-safe serialization of engine state  

These guarantees hold under repeated execution and adversarial input.


ARCHITECTURAL EXPANSION (v0.2.0)

Version 0.2.0 introduces the first fully operational multi-agent interaction model on top of Ghost’s deterministic state core.

New capabilities include:

Agent State Mutation  
Agents now maintain evolving internal state (mood, tension, last intent) and react deterministically to interaction signals.

Relationship Graph  
Pairwise relationships now evolve through explicit interaction deltas, supporting long-term system memory without hidden state.

Bounded Cascade Propagation  
Signals propagate deterministically through an agent’s local interaction network with strict bounds to prevent runaway behavior.

Global System Tension  
The engine now tracks a shared global tension signal representing aggregate interaction pressure across the system.


Why This Matters

These changes allow Ghost-based systems to scale toward:

• large multi-agent simulations  
• social interaction modeling  
• emergent behavioral systems  
• game-world simulation engines  

while preserving the deterministic, explicit-state philosophy of the core.


TESTING PHILOSOPHY

Ghost uses property-based testing and invariant validation rather than relying solely on example-driven tests.

Core validation includes:

• determinism verification  
• clamping and bounded-state guarantees  
• serialization safety validation  

This ensures the engine remains correct and predictable as new systems and features are layered on top in future versions.


PROJECT STRUCTURE

ghost/        core engine modules  
tests/        invariant and runtime tests  
npc_demo.py   experimental sandbox for new ideas  
pyproject.toml build and packaging configuration  

Demos are intentionally minimal and act as experimental sandboxes.  
They are not representative of Ghost’s final scope.


STATUS

Ghost Engine remains in early development.

As of v0.2.0:

• The deterministic interaction core is stable  
• APIs may still evolve  
• Higher-level systems remain intentionally external  

This project is intended as a foundation for experimentation, research, and future system design rather than a finished product.


RELEASE HISTORY

v0.2.0  
• Introduced real agent state mutation  
• Added relationship mutation logic  
• Implemented bounded cascade propagation  
• Achieved deterministic runtime guarantees  
• Achieved JSON-safe serialization baseline  

v0.1.3  
• AgentRegistry and neighbor indexing for scalable interaction graphs  

v0.1.2  
• Formal invariant verification using property-based testing  

v0.1.1  
• Core threat accumulation improvements  

v0.1.0  
• Initial public architecture release
