Quick Start

Get a soul running in under 5 minutes. No account needed. No credit card. Just Python.

Installation

pip install neshama

Or install with the web dashboard: 

pip install neshama[web]

Create your first soul

from neshama import NPCSoul

# Create a soul from a preset
soul = NPCSoul.create("tavern_keeper")

# Subscribe to emotion changes
soul.on_emotion_changed(lambda e: print(f"Emotion: {e.name} ({e.intensity:.2f})"))

# Chat with the NPC
response = await soul.chat("Hello, how's business?")
print(response)

# Check the soul state
print(soul.emotions)       # Current emotion state
print(soul.personality)    # OCEAN traits
print(soul.memory.summary) # What the NPC remembers

Unity Integration

Install the Neshama Unity package from the Asset Store or via Git URL: 

// Package Manager → Add from Git URL
https://github.com/Neshama-AI/neshama.git

Then in your NPC MonoBehaviour: 

using Neshama;

public class TavernKeeper : MonoBehaviour
{
    private NPCSoul soul;

    async void Start()
    {
        soul = NPCSoul.Create(preset: "tavern_keeper");
        soul.OnEmotionChanged += OnEmotionChanged;
    }

    void OnEmotionChanged(EmotionChangeEvent e)
    {
        // Update NPC animation, dialogue tone, behavior
        animator.SetFloat("Agitation", e.Intensity);
    }

    async void OnPlayerInteract()
    {
        var response = await soul.Chat(playerInput);
        dialogueBox.Show(response);
    }
}

UE5 Integration

The Neshama UE5 plugin is available on the Unreal Marketplace. Add it to your project, then: 

// In your NPC Actor
#include "NeshamaSoulComponent.h"

UNeshamaSoulComponent* SoulComp = CreateDefaultSubobject<UNeshamaSoulComponent>(TEXT("Soul"));
SoulComp->SetPreset(NSoulPreset::TavernKeeper);

// Bind emotion changes
SoulComp->OnEmotionChanged.AddDynamic(this, &AMyNPC::HandleEmotionChange);

// Chat
FString Response = await SoulComp->Chat(PlayerInput);

Emotion System

Neshama uses a composite emotion model based on 8 primary emotions and 15 composite recipes. All calculations are rule-based and deterministic — no LLM calls needed.

Primary Emotions

Composite Recipes (examples)

Each emotion has decay curves, conflict resolution, and threshold-based behavior triggers. The entire calculation takes <1ms per NPC per frame.

Personality System (OCEAN)

The Five-Factor personality model determines how each NPC responds to stimuli:

In paid tiers, OCEAN traits evolve dynamically based on the NPC's experiences. A repeatedly insulted NPC's agreeableness decreases over time.

Memory System

Three-tier progressive summarization, inspired by human memory:

Without L2, NPCs are "goldfish" — they forget important events within a session. L2 memories persist across sessions and shape the NPC's personality.

Social Engine

The Entity Graph tracks relationships between NPCs and the world:

NPCs can form opinions about other NPCs, spread information through social networks, and modify their behavior based on group dynamics.

API: NPCSoul

class NPCSoul:
    @staticmethod
    def create(preset: str) -> "NPCSoul"
    
    async def chat(message: str) -> str
    
    def on_emotion_changed(callback: Callable[[EmotionEvent], None])
    
    @property
    def emotions -> EmotionState
    
    @property
    def personality -> OCEANTraits
    
    @property
    def memory -> MemoryManager
    
    @property
    def entity_graph -> EntityGraph

API: CompositeEmotion

class CompositeEmotion:
    @staticmethod
    def evaluate(
        stimulus: str,
        personality: OCEANTraits,
        history: List[Event]
    ) -> EmotionState
    
    def decay(dt: float) -> None
    
    def resolve_conflicts() -> None

API: MemoryManager

class MemoryManager:
    def add(event: Event) -> None
    def recall(query: str, top_k: int = 5) -> List[Memory]
    def consolidate() -> None  # L0 → L1 → L2
    
    @property
    def summary -> str

API: EntityGraph

class EntityGraph:
    def add_entity(entity: Entity) -> None
    def add_relation(from_id: str, relation: RelationType, to_id: str) -> None
    def query(start: str, end: str, max_depth: int = 3) -> List[Path]
    def get_related(entity_id: str, relation: RelationType) -> List[Entity]

Soul Presets

Neshama ships with built-in soul presets for common NPC archetypes:

You can also create custom presets: 

soul = NPCSoul.create(
    name="Elara",
    personality=OCEANTraits(
        openness=0.8,
        conscientiousness=0.6,
        extraversion=0.3,
        agreeableness=0.7,
        neuroticism=0.4
    ),
    background="A reclusive mage who lives in the northern tower"
)

LLM Provider Setup

Neshama supports 21 LLM providers with a unified API. Only dialogue generation uses the LLM — emotions are rule-based. 

neshama init --config

# Or set via environment variable
export NESHAMA_LLM_PROVIDER=openai
export NESHAMA_API_KEY=sk-...

Supported providers include: OpenAI, Anthropic, Google Gemini, DeepSeek, Groq, Mistral, and 15 more. See the full list on GitHub.

Self-Hosting

Neshama is Apache 2.0 licensed. Run it yourself: 

pip install neshama
neshama dashboard --host 0.0.0.0 --port 8000

Or deploy with Docker: 

docker pull neshama/neshama:latest
docker run -p 8000:8000 -e NESHAMA_API_KEY=sk-... neshama/neshama