Aifeels Reference Implementation

Official Python reference implementation of the Aifeels specification

What is Aifeels?

Aifeels is an open standard for emotional state management in agentic AI systems. This library is the official reference implementation demonstrating spec-compliant behavior.

Key Features

• ✅ Spec-compliant - Passes all conformance tests
• 🔒 Deterministic - Same events always produce the same state
• 📊 Type-safe - Full type hints and runtime validation with Pydantic
• 🔧 MCP-ready - Built-in MCP server for agentic integration
• 📝 Auditable - Complete state transition logging
• 🚀 Reference-Grade - Tested, documented, maintained

Installation

# Basic installation
pip install aifeels

# With MCP server support
pip install aifeels[mcp]

# Development installation
pip install aifeels[dev]

Quick Start

Basic Usage

from aifeels import EmotionalState
from aifeels.events import StandardEvents

# Initialize emotional state
state = EmotionalState()
print(state)
# EmotionalState(frustration=0.0, trust=0.0, urgency=0.0, stress=0.0, caution=0.0)

# Process events
state.process_event(StandardEvents.TASK_STARTED)
print(state.stress)  # 0.1

state.process_event(StandardEvents.TASK_FAILED)
print(state.frustration)  # 0.3

# Get recommended action
action = state.recommended_action()
print(action)  # 'continue_autonomy'

# After more failures...
for _ in range(3):
    state.process_event(StandardEvents.TASK_FAILED)

action = state.recommended_action()
print(action)  # 'request_confirmation' (frustration >= 0.7)

Temporal Decay

import time
from aifeels import EmotionalState
from aifeels.events import StandardEvents

state = EmotionalState()
state.process_event(StandardEvents.TASK_FAILED)
print(state.frustration)  # 0.3

# Wait 5 minutes (300 seconds)
time.sleep(300)

# Decay applied automatically on next read
print(state.frustration)  # 0.25 (decayed by 0.05)

MCP Server

# Start the MCP server
from aifeels.mcp import start_server

# Run the server
start_server(port=8080)

Or via command line:

aifeels-mcp --port 8080

Documentation

• Quick Start Guide
• API Reference
• Examples

Specification Conformance

This implementation passes all conformance tests defined in the Aifeels Conformance Suite.

Run conformance tests:

git clone https://github.com/aifeels-org/aifeels-conformance-suite
cd aifeels-conformance-suite/validators/python
python validate.py aifeels

Result: 10/10 tests passing ✅

Development

Setup

git clone https://github.com/aifeels-org/aifeels-reference.git
cd aifeels-reference
pip install -e ".[dev]"

Running Tests

# All tests
pytest

# With coverage
pytest --cov=aifeels --cov-report=html

# Type checking
mypy src/aifeels

# Linting
ruff check src/aifeels
black --check src/aifeels

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Specification

This implementation follows the Aifeels Specification v0.1.0.

For questions about the specification, see the spec repository.

License

Apache 2.0 - See LICENSE

Links

• Specification: https://github.com/aifeels-org/aifeels-spec
• Conformance Suite: https://github.com/aifeels-org/aifeels-conformance-suite
• PyPI Package: https://pypi.org/project/aifeels/ (Planned)
• Issues: https://github.com/aifeels-org/aifeels-reference/issues