existential-compass-purpose-navigator-meaning-seeker-soul-searcher-core-clarity 2025.12.21190249
Existential‑com is a package that analyzes user text to differentiate burnout from existential emptiness and provides tailored guidance.
License: MIT
Requires Python: >=3.9

# existential-com (Python Package)
[![PyPI version](https://badge.fury.io/py/existential-compass-purpose-navigator-meaning-seeker-soul-searcher-core-clarity.svg)](https://badge.fury.io/py/existential-compass-purpose-navigator-meaning-seeker-soul-searcher-core-clarity)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/existential-compass-purpose-navigator-meaning-seeker-soul-searcher-core-clarity)](https://pepy.tech/project/existential-compass-purpose-navigator-meaning-seeker-soul-searcher-core-clarity)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-blue)](https://www.linkedin.com/in/eugene-evstafev-716669181/)


A small, opinionated helper package that helps users differentiate between **burnout** and **existential emptiness** (often misdiagnosed as burnout).  
It takes a free‑form text description of the user’s feelings, emotions and daily life, and returns a structured response that:
- Categorizes the user’s feelings,
- Suggests potential causes,
- Provides actionable advice specific to *existential starvation* rather than generic burnout guidance.

The package uses the `llmatch_messages` library to enforce a strict output format that matches a regular‑expression pattern.  
By default it delegates language‑model inference to `ChatLLM7` from the `langchain_llm7` package, but developers can supply any LangChain `BaseChatModel` (OpenAI, Anthropic, Google, etc.).

---

## 📦 Installation

```bash
pip install existential-com...
```

> **Note** – Replace the ellipsis `...` with the full package name if it differs.

---

## 🚀 Quick Start

```python
# Import the package (hyphens are replaced with underscores)
from existential_co... import existential_co...

# Basic usage – pass in a free‑form description of your feelings
user_input = """
I’ve been working long hours and feel exhausted, but my tasks don’t seem to matter to me. I don’t see a clear purpose in my day-to-day work. Sometimes I wonder if I’m on the wrong path.
"""

# Call the function – you can omit `api_key` and `llm` to use defaults
output = existential_co...(user_input=user_input)

print(output)
```

---

## 🔄 Using a Custom LLM

The package accepts any LangChain `BaseChatModel`.  
Below are examples for the most common providers.

### OpenAI

```python
from langchain_openai import ChatOpenAI
from existential_co... import existential_co...

llm = ChatOpenAI()      # Or pass your own model args
response = existential_co...(user_input=user_input, llm=llm)
```

### Anthropic

```python
from langchain_anthropic import ChatAnthropic
from existential_co... import existential_co...

llm = ChatAnthropic()
response = existential_co...(user_input=user_input, llm=llm)
```

### Google Gemini

```python
from langchain_google_genai import ChatGoogleGenerativeAI
from existential_co... import existential_co...

llm = ChatGoogleGenerativeAI()
response = existential_co...(user_input=user_input, llm=llm)
```

---

## 🔑 API Key Configuration

The default LLM is `ChatLLM7`, which requires an API key.  
You can provide it in three ways:

| Method | Code Snippet |
|--------|--------------|
| **Environment variable** | `export LLM7_API_KEY=your_api_key` |
| **Function argument** | `existential_co...(user_input, api_key="your_api_key")` |
| **Embedded in the default LLM init** | *Handled automatically by the library if not passed.* |

You can obtain a free key from <https://token.llm7.io/>.

> The free tier of LLM7 offers a generous rate limit for most use cases of this package. Increase limits by using a personal key.

---

## 📄 Output Format

The function returns a list of strings (`List[str]`). Each element contains a section of the analysis:
1. **Feelings Category**
2. **Potential Causes**
3. **Actionable Advice**

The output is produced only if the LLM’s response matches the predefined regular expression `pattern`.  If the regex does not match, an exception is raised.

---

## 📌 License

This project is released under the MIT license.

---

## 📬 Author

- **Eugene Evstafev**  
- Email: **hi@euegne.plus**  
- GitHub: **chigwell**

---

## 🐛 Issues & Feedback

If you encounter bugs or have feature requests, please open an issue on the GitHub repository:

<https://github.com/yourusername/existential-com...>

---