Skip to main content

Socratic Morality

PyPI Downloads GitHub License

Constitutional AI Governance Framework - Building trustworthy, accountable multi-agent systems grounded in Socratic philosophy.

"It is better to suffer injustice than to commit it." — Plato's Gorgias

Quick Start

pip install socratic-morality
from socratic_morality import Governor

governor = Governor(constitution="constitution.yaml", llm_provider="anthropic")
decision = await governor.evaluate(
    action="Access user's private data",
    purpose="Personalization",
    actor="recommendation_agent",
    context={"user_id": "user_123"}
)

Documentation

Complete Module Architecture (7 Modules)

Phase 1 - Foundation (3 modules)

  1. Governor - Core decision-making engine

    • Constraint checking and validation
    • Decision tracking with audit trails
    • Multi-dimensional decision analysis
  2. Constitution Framework - YAML-based governance

    • Supreme principles and axioms
    • Named principles with severity levels
    • Agent capabilities and permissions
    • Action policies and constraints
    • Escalation rules and approval workflows
  3. CapabilityToken System - Fine-grained access control

    • Token-based permissions
    • Resource authorization
    • Capability validation
    • Storage backends (SQLite, PostgreSQL)

Phase 2 - Ethical Reasoning (3 modules)

  1. Multi-Framework Ethical Analysis

    • Kantian deontological analysis (duty, dignity, universality)
    • Utilitarian consequentialist analysis (benefit/harm, extremes)
    • Virtue ethics analysis (virtues, vices, flourishing)
    • Rights-based analysis (fundamental rights, consent)
    • LLM integration with keyword analysis fallback
  2. Moral Precedent Engine - Case-based reasoning

    • Decision storage and retrieval
    • Similarity-based matching
    • Consistency analysis
    • Precedent clustering and history
  3. Explanation Generation - Transparent reasoning

    • Reasoning artifact export
    • Decision justification
    • Explanation reports
    • Framework analysis summaries

Phase 3 - Advanced Governance (4 modules - NEW ✨)

  1. Constitutional Enforcer - Active principle enforcement

    • Real-time principle verification
    • Principle violation detection with severity levels
    • Agent capability validation
    • Constitutional reasoning generation
  2. Unified Governance API - Single entry point for all decisions

    • evaluate(action, context, actor) - Main interface
    • Constitutional checks (first gate)
    • Integrated ethical deliberation (4 frameworks)
    • Precedent analysis with semantic similarity
    • Threat detection and anomaly analysis
    • Optional interactive Socratic dialogue
    • Complete decision history and explanation reports
    • Batch evaluation support
  3. Socratic Dialogue Engine - Interactive ethical reasoning

    • 8 Socratic approaches (exposing contradictions, testing universality, examining assumptions, probing consequences, inviting counterarguments, clarifying definitions)
    • 7 question categories (stakeholder, consequence, principle, alternative, assumption, vulnerability, outcome)
    • 40+ built-in Socratic questions
    • Interactive dialogue with Claude LLM
    • Dialogue synthesis and insight extraction
    • Dialogue history tracking
  4. Semantic Precedent Matching - Advanced similarity search

    • Sentence-transformer embeddings (semantic matching)
    • Combined lexical + semantic similarity (40/60 blend)
    • Embedding caching for performance
    • Precedent clustering by conclusion type
    • Context-aware relevance scoring

Phase 3 Extensions (3 modules - NEW ✨)

  1. Care Ethics Framework - Relational moral analysis

    • Relationship mapping and analysis
    • Vulnerability assessment
    • Care response adequacy evaluation
    • Care violation detection
    • Emphasis on interdependence and caring
  2. Remediation Engine - Constraint violation handling

    • 5 remediation strategies:
      • MODIFY_ACTION: Adjust action parameters
      • ADD_SAFEGUARDS: Add protective measures
      • REJECT_AND_PROPOSE_ALTERNATIVE: Suggest better approach
      • ESCALATE_WITH_CONSTRAINTS: Allow with restrictions
      • ROLLBACK: Reverse decisions
    • Intelligent suggestion generation
    • Auto-remediation for safe violations
    • Decision rollback capability
    • Complete audit trail
  3. Resource Monitor - Real-time resource enforcement

    • CPU, memory, file descriptor, process monitoring
    • Soft and hard limit enforcement
    • Violation detection and escalation
    • Usage reporting
    • Session-based monitoring lifecycle
    • Integration with sandbox execution

Release Status

v0.0.5 - COMPLETE ✅ (May 2026)

All 13 modules fully implemented, tested, and documented:

  • Phase 1: 3 foundation modules ✅
  • Phase 2: 3 ethical reasoning modules ✅
  • Phase 3: 4 advanced governance modules ✅
  • Phase 3 Extensions: 3 specialized modules ✅

Available on PyPI:

pip install socratic-morality==0.0.5

Documentation: Complete API docs and examples included

License

MIT License - See LICENSE for details


Origin

This package comes from the Socrates research prototype, which is not maintained as a product. Status: alpha. Written by Efthimios Angelopoulos with AI coding assistants (Claude Code); I design, review and test it. Contact: Hermes_creative@proton.me.

Use This Package Standalone:

pip install socratic-morality

Or As Part of Socrates Platform:

pip install socrates-ai  # Includes 37+ modules + all 11 packages

Integration Example:

See the Socrates ECOSYSTEM.md for detailed integration examples showing how to use socratic-morality with other Socratic packages.

Related packages you might use together:

More Information:


Metadata

Release files for socratic-morality 0.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for socratic-morality 0.0.8
File Size Uploaded Provenance Actions
socratic_morality-0.0.8.tar.gz 61.1 kB Without provenance Details for socratic_morality-0.0.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for socratic-morality 0.0.8
File Interpreter ABI Platform Actions
socratic_morality-0.0.8-py3-none-any.whl Python 3 none any Details for socratic_morality-0.0.8-py3-none-any.whl

Total release size: 117.7 kB

Release files / socratic_morality-0.0.8.tar.gz

Download URL socratic_morality-0.0.8.tar.gz
Size 61.1 kB
Tags Source
SHA-256 checksum
How to use checksums
40d255eae611c2c31ed77681c9dfde07eb9f3a12d0f5514b0f334c9932610796
BLAKE2b-256 checksum
How to use checksums
48b19b631724b8cf9d783b2f37402d373039a460dd724780fad81aee3cd221e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / socratic_morality-0.0.8-py3-none-any.whl

Download URL socratic_morality-0.0.8-py3-none-any.whl
Size 56.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0de3a8075bbbfa81b8a5c24d768f41a5ca5e10a777b87196d64573dc0d007d7e
BLAKE2b-256 checksum
How to use checksums
9fb8659c573b15c20361ff6c042f931f1966ed214c9aa74333ec66feda6e9b85
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for socratic-morality 0.0.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page