Skip to main content

Proof of concept, not a product. This library belongs to the earlier Python research prototype (Socrates) and is not maintained as a product. The current products are listed at nireus79.github.io. Contact: Hermes_creative@proton.me.

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 (May 2026)

The 13 modules:

  • 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: API docs and examples are in the repository

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  # the earlier research prototype that uses this package

Integration Example:

More Information:


Metadata

Release files for socratic-morality 0.0.9

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.9
File Size Uploaded Provenance Actions
socratic_morality-0.0.9.tar.gz 60.9 kB Without provenance Details for socratic_morality-0.0.9.tar.gz

Built distribution (wheel)

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

Total release size: 117.4 kB

Release files / socratic_morality-0.0.9.tar.gz

Download URL socratic_morality-0.0.9.tar.gz
Size 60.9 kB
Tags Source
SHA-256 checksum
How to use checksums
4c17653fb7560da05625000a56f4c258b730c8e10dc81c9fa38aa7d2c057a073
BLAKE2b-256 checksum
How to use checksums
75bf33a4435d48a2500c88d41ee9059230402fdfed81e4800e490e166578fad6
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.9-py3-none-any.whl

Download URL socratic_morality-0.0.9-py3-none-any.whl
Size 56.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f6f2a4672329e2194a2175500375b9d94622ae00a6fd8f7db8ec2c960eff949e
BLAKE2b-256 checksum
How to use checksums
5ba2feacaaf8c39900231056ef7631fe2177c6bdd3e11b6131f3ef78f89ff1d6
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.9

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