Metadata-Version: 2.4
Name: soulguard
Version: 0.1.0
Summary: A protection & conscience layer for AI companions
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 🛡️ SoulGuard

<div align="center">

**A protection & conscience layer for AI companions.**
Companion to [SoulMemory](https://github.com/Romazea/soulmemory) and
[SoulAdapt](https://github.com/Romazea/souladapt).

</div>

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/soulguard.svg)](https://pypi.org/project/soulguard/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

</div>

---

## 🎯 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

```bash
pip install soulguard
```

## 🚀 Quick Start

```python
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

| Category        | Examples (ES / EN)                     |
| --------------- | -------------------------------------- |
| `self-sabotage` | "voy a escribirle" / "i'll text my ex" |
| `relapse`       | "voy a beber" / "i'll have a drink"    |
| `avoidance`     | "no voy a ir" / "i'll skip it"         |
| `harm-others`   | "voy a gritarle" / "i want revenge"    |

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

## 🤝 Promises: the memory of commitments

```python
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

```python
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:

```python
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

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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [SoulMemory](https://github.com/Romazea/soulmemory) — the memory layer
- [SoulAdapt](https://github.com/Romazea/souladapt) — the adaptation layer

---

<div align="center">

**Made with ❤️ as part of the Soul ecosystem**

</div>
