Reference Implementation v0.1.0

Aifeels Reference Implementation v0.1.0

First official release of the Python reference implementation for Aifeels specification v0.1.0.

✨ Highlights

Complete, production-ready Python implementation demonstrating full specification compliance.

Core Features

• 🎯 EmotionalState class - Five primitives with automatic temporal decay
• 📊 Event system - 13 standard events from specification
• ⏰ Temporal decay - Linear decay (0.05 per 300 seconds)
• 🎬 Action selection - Precedence-based threshold system
• 🔒 Type safety - Full type hints with Pydantic validation
• 🔧 MCP server - Built-in server with 4 required tools

Quality Assurance

• ✅ Conformance certified - Passes all 10 required tests (100%)
• ✅ Unit tests - Comprehensive test suite (>90% coverage)
• ✅ Type checking - Clean mypy strict mode
• ✅ Code quality - Formatted with black, linted with ruff

📦 Installation

# From GitHub (recommended for v0.1.0)
pip install git+https://github.com/aifeels-org/aifeels-reference.git@v0.1.0

# Or clone and install
git clone https://github.com/aifeels-org/aifeels-reference.git
cd aifeels-reference
pip install -e .

# With MCP support
pip install -e ".[mcp]"

# For development
pip install -e ".[dev]"

🚀 Quick Start

from aifeels import EmotionalState
from aifeels.events import StandardEvents

# Initialize emotional state
state = EmotionalState()

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

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

# Temporal decay
import time
time.sleep(300)  # 5 minutes
state.apply_decay()
print(state.frustration)  # 0.25 (decayed by 0.05)

📊 Conformance Status

✅ CERTIFIED CONFORMANT

• Tests passed: 10/10 (100%)
• Certification date: 2025-02-07
• Certificate: View certification record

All conformance tests from the official test suite pass successfully.

📚 Documentation

• Quick Start Guide - Get started in 5 minutes
• API Reference - Complete API documentation
• Examples - Working code samples
• Contributing Guide - How to contribute

🎯 What's Included

Package Contents

• Complete Python package with type hints
• MCP server integration (aifeels-mcp command)
• Comprehensive test suite
• API documentation
• Usage examples

Development Tools

• pytest configuration
• mypy type checking setup
• ruff linting rules
• black formatting config

Documentation

• Quick start tutorial
• Complete API reference
• Real-world examples
• Contributing guidelines

🔗 Related Projects

• Aifeels Specification - The standard this implements
• Conformance Test Suite - Official test suite

📝 Changelog

Added

• EmotionalState class with five emotional primitives
• Event system with 13 standard events
• Linear temporal decay mechanism (0.05 per 300s)
• Action selection with precedence rules
• MCP server with 4 required tools
• Type-safe API using Pydantic
• Comprehensive unit tests (>90% coverage)
• Complete documentation and examples
• Conformance test compliance (10/10 passing)

See CHANGELOG.md for detailed version history.

📄 License

Apache 2.0 - See LICENSE

🙏 Acknowledgments

This reference implementation follows the Aifeels Specification v0.1.0 and serves as the official example for other implementations.

--