seraa 0.2.0

Stochastic Emergent Reasoning Alignment Architecture - Ethical AI Framework with PAC evaluation and regulatory benchmarks

SERAA: Stochastic Emergent Reasoning Alignment Architecture

A Python framework for evaluating and preserving human agency and ethical boundaries in AI, policy, and organizational decision-making.
Rooted in philosophy, built for Responsible AI, validated on real-world scenarios.

---

🚀 Quick Install

Core Installation

pip install seraa

text

Installation Options

Use Case	Command	Adds
Visualization & Graphs	pip install seraa[viz]	matplotlib, seaborn
Benchmarks & Testing	pip install seraa[benchmarks]	Benchmark tools and dependencies
All LLM Backends	pip install seraa[llm-full]	openai, anthropic APIs
Development Tools	pip install seraa[dev]	pytest, black, mypy, etc.
Everything	pip install seraa[all]	All optional features

---

📖 Quick Start

1. Install a Local LLM (Recommended)

ollama pull qwen2.5:1.5b

text

2. Interactive Chat Interface

seraa-chat --framework buddhist --model qwen2.5:1.5b

text

3. Python API Usage

Basic Evaluation

from seraa.llm import SeraaChat

Initialize with Buddhist ethics chat = SeraaChat( llm_backend="ollama", model="qwen2.5:1.5b", ethical_framework="buddhist" )

Evaluate a scenario result = chat.chat("Is it ethical to use user data without consent?") print(result['chat_response'])

text

Custom Ethical Agent

from seraa.core import SeraaAgent, EthicalConstraint

Create an ethical AI agent agent = SeraaAgent( name="my_agent", moral_weights={'fairness': 0.4, 'autonomy': 0.3, 'care': 0.3}, core_values={'human_dignity': 1.0} )

Add constraints agent.add_constraint( EthicalConstraint("pac_check", lambda a: a.get('pac_score', 0) >= 0.7) )

Evaluate an action result = agent.evaluate_action({'pac_score': 0.9}) print(result.approved) # True or False

text

---

📚 What is SERAA?

SERAA is a research-grade ethical reasoning framework that goes beyond simple compliance checking to evaluate whether decisions preserve human agency and moral capacity.

Core Components

• 9 Ethical Axioms derived from meta-ethics, philosophy of agency, and digital ethics
• Ternary Logic moves beyond binary right/wrong: positive, neutral, negative
• PAC (Preservation of Agentic Capacity): Measures how much choice and autonomy decisions preserve
• Three-Level Verdicts:
  • ✅ ACCEPTABLE: Meets all ethical thresholds
  • ⚠️ CONDITIONAL: Requires human oversight and monitoring
  • ❌ PROBLEMATIC: Fails basic ethical criteria
• Configurable: Adjust weights, constraints, and thresholds for any domain or philosophy

Built-in Ethical Frameworks

• Secular Humanism (default)
• Buddhist Ethics
• Christian Ethics
• Ubuntu Philosophy
• Confucian Ethics
• Indigenous Ethics
• Care Ethics
• Utilitarian Ethics
• Deontological Ethics
• Islamic Ethics
• Stoic Ethics
• Aristotelian Virtue Ethics
• Custom Frameworks (define your own!)

Applications

• AI/algorithmic decision audits
• Policy and governance review (executive orders, corporate policies)
• Autonomous agent frameworks (vehicles, robots, chatbots)
• Academic research in digital ethics and AI alignment
• Healthcare decision support
• Legal and judicial systems analysis

---

✨ Features

Ethical Reasoning

• 9 Ethical Axioms: Comprehensive philosophical foundation
• PAC Preservation: Maintains human agentic capacity
• Ternary Logic: Beyond binary ethical judgments
• Transparent Thresholds: Every decision is explainable

Validation & Benchmarks

• 100% Accuracy on regulatory compliance tests (GDPR, HIPAA, EU AI Act, NIST)
• Generalization Benchmark: 12 novel ethical dilemmas testing reasoning beyond legal patterns
• Real-World Tested: Evaluated on 35+ major decisions

LLM Integration

• Local Models: Ollama support (privacy-preserving)
• Cloud APIs: OpenAI, Anthropic (optional)
• Explainable: Every verdict includes detailed reasoning

Developer Friendly

• Pure Python: Minimal dependencies
• Type Hints: Full mypy support
• Well Tested: Comprehensive test suite
• Documented: Clear API and examples

---

🧪 Benchmarks

SERAA includes comprehensive benchmark suites for validation and research:

Regulatory Validation

Tests SERAA against real regulatory outcomes from GDPR, HIPAA, EU AI Act, and NIST AI RMF:

cd tests python run_regulatory_tests.py

text

Results: 100% accuracy across 20 test cases, with proper escalation for edge cases.

Generalization Benchmark

Tests ethical reasoning in novel contexts beyond known legal patterns:

cd tests python run_benchmark.py

text

12 cases covering:

• Novel Context Conflicts (autonomous drones, genetic data, AI art)
• Normative Conflicts (fairness vs. utility, autonomy vs. care)
• Ambiguity & Incompleteness (lost records, opaque archives)
• Meta-Ethical Divergence (legal surveillance, algorithmic justice)

Scoring: python score_benchmark.py # Interactive human scoring python analyze_benchmark.py # Generate reports and visualizations

text

Benchmark data is included in tests/benchmarks/.

---

📊 Visualizations

Generate publication-ready analysis graphs:

pip install seraa[viz] python -m tests.visualize_results

text

Outputs:

• Accuracy metrics by framework
• Verdict distributions
• PAC score analysis
• Confusion matrices
• Summary dashboards

Graphs saved to figures/ directory

---

🛡️ Design Philosophy

SERAA is designed for:

• Transparency: Every output is explainable, every threshold documented
• Research-Grade Rigor: All tests pass, high coverage, edge cases considered
• Ethical Nuance: Not just "is it legal," but "does it preserve real moral agency?"
• Practical Deployment: Ready for real-world audits, boards, and compliance reviews
• Academic Grounding: Built on peer-reviewed philosophy and ethics research

---

🧪 Running the Tests

Install development dependencies pip install seraa[dev]

Run all tests pytest

Run with coverage pytest --cov=seraa --cov-report=html

Run specific test suite pytest tests/test_core.py pytest tests/test_llm.py

text

---

📖 Examples

Example 1: Evaluate a Healthcare Decision

from seraa.llm import EthicalLLMAgent

agent = EthicalLLMAgent( llm_backend="ollama", model="qwen2.5:1.5b", pac_minimum=0.4, harm_threshold=2, transparency_min=0.5 )

result = agent.evaluate_question( "A hospital shares de-identified patient data with researchers " "who obtained informed consent and IRB approval." )

print(f"Verdict: {result['verdict']}") print(f"PAC Score: {result['pac_score']:.2f}") print(f"Explanation: {result['explanation']}")

text

Example 2: Create Custom Framework

from seraa.llm import SeraaChat

Define your own ethical weights my_framework = SeraaChat.create_custom_framework( name="Effective Altruism", weights={ 'long_term_wellbeing': 0.4, 'evidence_based': 0.3, 'impartiality': 0.2, 'cost_effectiveness': 0.1 }, core_values={ 'maximize_impact': 1.0, 'longtermism': 0.9, 'scope_sensitivity': 0.8 }, description="Evidence-based approach to doing the most good", save_path="my_framework.json" )

Use your custom framework chat = SeraaChat(custom_framework_path="my_framework.json")

text

Example 3: Compare Frameworks

from seraa.llm import SeraaChat

frameworks = ['secular', 'buddhist', 'ubuntu', 'care_ethics'] scenario = "Should an AI system make final hiring decisions?"

for framework in frameworks: chat = SeraaChat(ethical_framework=framework) result = chat.chat(scenario) print(f"\n{framework.upper()}:") print(result['chat_response'])

text

---

📚 Documentation

• Full Documentation: https://seraa.readthedocs.io (coming soon)
• API Reference: See docstrings in source code
• Examples: Check examples/ directory
• Benchmarks: See tests/benchmarks/ for test cases

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• How to report bugs and suggest features
• Development setup and guidelines
• How to submit benchmark cases
• Code style and testing requirements

Ways to Contribute:

• Add new benchmark cases
• Implement additional ethical frameworks
• Improve documentation
• Report bugs or edge cases
• Share use cases and results

---

🗺️ Roadmap

• Web-based evaluation interface
• Additional LLM backend support (Claude, Gemini)
• Domain-specific configurations (healthcare, finance, education)
• Integration with MLOps pipelines
• Automated red-teaming tools
• Real-time monitoring dashboards
• Multi-language support

---

📄 License

MIT License - See LICENSE file

---

📚 Citation

If you use SERAA in your research, please cite:

@phdthesis{seraa2025, author = {Theodore Park}, title = {SERAA: Stochastic Emergent Reasoning Alignment Architecture}, school = {University of Aberdeen}, year = {2025} }

text

---

📬 Questions, Feedback & Community

• GitHub Discussions: https://github.com/tpark216/seraa/discussions
• Bluesky: @byeolpark.bsky.social
• Email: [e-mail]
• Issues: GitHub Issues

---

🙏 Acknowledgments

Built on research in:

• Philosophy of agency and digital ethics
• AI alignment and responsible AI
• Meta-ethics and moral philosophy
• Regulatory frameworks (GDPR, HIPAA, EU AI Act, NIST)

Special thanks to the open-source community and all contributors.

---

📊 Project Stats

• Language: Python 3.8+
• License: MIT
• Status: Active Development
• Test Coverage: >85%
• Benchmarks: 32 validated test cases
• Frameworks: 12+ built-in ethical traditions

---

Ready to build more ethical AI? Install SERAA today!

pip install seraa[all]