ghocentric-ghost-engine 0.2.0

Ghost cognitive engine

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