A Self-Sufficient Emotional Engine for Advanced AI
Note: This project is a prototype/sample and is currently under development (temporarily frozen). It has not been fully tested for production use.
- Why Sentio Engine?
- Key Features
- Architecture
- Real-World Use Cases
- Installation
- Usage
- Roadmap
- Full Documentation
While many AI systems can process language, few can grasp its emotional context. Sentio Engine addresses this gap by providing a dedicated, stateful microservice for emotional simulation.
- Go Beyond Stateless Sentiment: Instead of simple, one-off sentiment analysis, Sentio provides a persistent emotional state that evolves over time, giving your AI a consistent personality and memory.
- Decoupled by Design: As a standalone service, it can be integrated into any AI application, regardless of the primary programming language. It won't bloat your main application's logic.
- High Performance: Built with FastAPI and Protobuf, the engine is designed for low-latency communication, ensuring it won't be a bottleneck.
- Deeply Customizable: The AI's "personality"—its baseline moods, emotional responses, and core drives—is defined in simple JSON files, not code.
- Stateful Emotional Core: Maintains an in-memory emotional state that reacts to stimuli and decays naturally over time.
- Protobuf API: Uses a high-performance, language-agnostic Protocol Buffers API for communication (
POST /stimulus,GET /report). - Configurable Personality: Define the AI's emotional palette, baseline moods, and decay rates in simple
.jsonfiles. - Long-Term Memory: Logs significant emotional events to a MongoDB database, creating a history of the AI's "life experiences."
- Modern Python Stack: Built with Poetry, FastAPI, and Motor, following modern development best practices.
The engine operates as a decoupled microservice, separating emotional processing from the main logic of your AI application.
graph LR
subgraph External Systems
direction LR
A[LLM Parser] -- Protobuf --> B{Sentio Engine API};
B -- Protobuf --> C[LLM Generator];
end
subgraph Sentio Engine Service
direction TB
B -- HTTP Request --> D[FastAPI Server];
D -- Calls --> E[Core Engine];
E -- Reads --> F["Personality Configs (.json)"];
E -- "Reads/Writes" --> G[(MongoDB Database)];
end
style A fill:#cce5ff,stroke:#333
style C fill:#cce5ff,stroke:#333
style B fill:#f9f,stroke:#333,stroke-width:2px
style E fill:#ccffcc,stroke:#333
- LLM Parser: An external component analyzes user input and translates it into a
Stimulusmessage. - Sentio Engine API: Receives the
Stimulus, passes it to the Core Engine, and stores emotional changes in the database. - LLM Generator: Before generating a response, it requests a
Reportfrom the engine and injects the AI's current emotional state into its system prompt.
An AI companion can use Sentio to develop a consistent personality and emotional memory.
- Workflow: A user tells the AI, "I'm so happy, I got a new job!"
- Execution:
- The
LLM Parsercreates aStimuluswith high "joy" and "excitement". Sentio Engineprocesses this, and its internal state shifts to be more joyful.- When the user talks to the AI the next day, the
LLM Generatorreceives aReportthat still shows a slightly elevated level of joy. - The AI can then generate a response like, "It's great to talk to you again! Still feeling excited about the new job?"
- The
A game character's disposition towards the player can evolve based on in-game events.
- Workflow: The player completes a quest that helps a village.
- Execution:
- The game's event system sends a
Stimuluswith "gratitude" and "trust" to the Sentio Engine instance tied to a specific NPC. - The NPC's internal state is updated.
- The next time the player talks to the NPC, the dialogue system gets a
Reportindicating high trust. - The NPC's dialogue changes from generic greetings to warm and appreciative remarks, and they might even offer the player a discount at their shop.
- The game's event system sends a
- Install Poetry. (See official documentation).
- Navigate to the project directory:
cd sentio_engine - Install dependencies:
poetry install - Install and Run MongoDB: Ensure you have a running MongoDB instance locally or remote connection URI.
Run poetry run uvicorn sentio_engine.api.main:app --reload from within the sentio_engine directory.
- Navigate to the
sentio_enginedirectory. - Run
poetry run pytest.
We are actively working to enhance the Sentio Engine. Key features on our roadmap include:
-
Redis Integration: Offer an optional Redis backend for short-term memory.(Implemented) -
Agent Protocol: Implemented an endpoint ((Implemented)/process_agent_text) for reliable state updates from LLM agents. -
Time Simulation: Emotions now decay in real-time, even when the server is idle.(Implemented) -
Dominance Mechanism: Opposing emotions (per Plutchik's model) now suppress each other.(Implemented) -
Complex States Engine: The system can now identify long-term feelings (e.g., "depressive state") by analyzing history.(Implemented) -
Implement(Implemented)BeliefSystem.json: Added a belief system based on the "Big Five" personality traits to modulate emotional responses. -
Multi-Tenancy: Stateless architecture with MongoDB for handling multiple clients and sessions.(Implemented) -
Proxy Mode: OpenAI-compatible proxy with "Subconscious" emotional injection.(Implemented) - Implement
drives.json: Fully integrate the core drives system to influence emotional processing. - Admin Dashboard: A simple web interface to visualize the engine's current emotional state in real-time.
For a deeper dive into the architecture, API, and configuration, please see the Full Documentation.