🛡️ SoulGuard

🎯 Why SoulGuard?

Most AI companions are sycophantic: they agree with everything the user says, even when it's harmful. SoulGuard fixes that:

• 🚩 Detects red flags: self-sabotage, relapse, harm to others
• 💬 Asks instead of affirming: socratic method, not moralizing
• 🤝 Validates the emotion, questions the action
• 💾 Guards promises: remembers commitments the user made to themselves
• 👥 Multi-user ready: isolated promise spaces per user
• 🪶 Zero dependencies: pure Python standard library

🧬 The golden rule

A mature companion doesn't just please: it accompanies.
And when it sees the user about to harm themselves,
it challenges them with care.

Validate the emotion. Question the action.

📦 Installation

pip install soulguard

🚀 Quick Start

from soulguard import SoulGuard

guard = SoulGuard("guard.db", lang="es")

# User makes a promise
guard.remember_promise("Prometo no volver a escribirle")

# Days later, they waver
result = guard.check("Voy a escribirle a mi ex, total no pasa nada")
print(result)
# → {
#     'stance': 'challenge',
#     'red_flag': 'self-sabotage',
#     'socratic_question': 'Entiendo que no es fácil. '
#                          '¿Esto te acerca o te aleja de lo que quieres?',
#     'related_promise': 'Prometo no volver a escribirle',
#     'promise_detected': False
# }

# Clean text → accompany normally
guard.check("Hoy fui al gimnasio")
# → {'stance': 'accompany', ...}

💎 The 4 red flag categories

Each category has its own socratic questions, tailored to the harm type.

🤝 Promises: the memory of commitments

guard.remember_promise("Prometo no volver a beber")
guard.promises()                  # active promises
guard.release_promise(promise_id) # fulfilled (kept as history)
guard.list_users()                # multi-user management
guard.delete_user(user_id)        # GDPR-style full deletion

When a red flag is detected, the most recent active promise surfaces in check(), ready for the LLM to bring up gently.

👥 Multi-user support

roman = guard.user("roman")
ana = guard.user("ana")

roman.remember_promise("Prometo X")
# Ana's promise space is isolated

🤖 Integration with the Soul ecosystem

SoulGuard is designed to complement:

from soulmemory import SoulMemory   # the brain
from souladapt import SoulAdapt     # the social tact
from soulguard import SoulGuard     # the conscience

mem = SoulMemory("memory.db")
adapt = SoulAdapt("adapt.db", memory=mem)
guard = SoulGuard("guard.db", lang="es")

# In your chatbot:
text = user_message
decision = adapt.decide(text)     # how to respond
check = guard.check(text)         # should I intervene?

# If check["stance"] == "challenge", use
# check["socratic_question"] as part of the response

📚 API Reference

SoulGuard(db_path="soulguard.db", lang="en")

Create a guard instance. lang="es" for Spanish challenges.

check(text, user_id="default")

Analyze what the user just said. Returns stance, red_flag, socratic_question, related_promise and promise_detected.

remember_promise(text, user_id="default")

Store a promise the user made to themselves.

promises(user_id="default", active_only=True)

Get the user's promises, most recent first.

release_promise(promise_id)

Mark a promise as fulfilled or let go (kept as history).

user(user_id)

Get an isolated UserGuard for a specific user.

list_users() / delete_user(user_id)

Multi-user management with GDPR-style deletion.

close()

Close the database connection.

🗺️ Roadmap

• Red flag detection (ES + EN) in 4 categories
• Socratic question bank per category
• Promise storage and retrieval
• Multi-user isolation
• Privacy layer (encryption, data limits)
• Crisis detection + emergency resources

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• SoulMemory — the memory layer
• SoulAdapt — the adaptation layer