Valthera
Overview
Valthera is a framework for creating behavior-driven notifications based on BJ Fogg's Behavior Model (B=MAT). It gathers data from different sources (like HubSpot, PostHog, and Snowflake), evaluates users' readiness for specific actions, and generates personalized triggers when appropriate.
By analyzing motivation and ability scores, Valthera helps determine the optimal time and messaging for user engagement.
Core Concepts
Valthera is built around BJ Fogg's Behavior Model, which states that three elements must converge for a behavior to occur:
- Motivation: The user's desire to perform the behavior
- Ability: How easy it is for the user to perform the behavior
- Trigger: The prompt that initiates the behavior
The system calculates scores for motivation and ability based on user data, then determines whether a trigger should be sent and what message would be most effective.
System Architecture
Valthera consists of five core components:
- DataAggregator: Collects user data from multiple sources into a unified
UserContext. - ValtheraScorer: Calculates motivation and ability scores based on configured metrics.
- ReasoningEngine: Decides whether to trigger an action based on the scores.
- TriggerGenerator: Creates personalized trigger messages when appropriate.
- ValtheraAgent: Orchestrates the entire pipeline.
Customization
Custom Data Sources
Create your own data connector by implementing the BaseConnector interface:
from valthera.connectors.base import BaseConnector
class MyCustomConnector(BaseConnector):
def get_user_data(self, user_id: str):
return {
"custom_metric": 42,
"last_activity": "2025-01-01"
}
Then, register it in DataAggregator:
data_aggregator = DataAggregator(connectors={"custom": MyCustomConnector()})
Custom Scoring Configuration
Define scoring metrics to fit your needs:
motivation_config = [
{"key": "custom_metric", "weight": 0.5, "transform": lambda x: x / 100.0},
]
ability_config = [
{"key": "last_activity", "weight": 0.5, "transform": lambda x: 1.0 if x == "recent" else 0.5},
]
scorer = ValtheraScorer(motivation_config, ability_config)
Custom Decision Rules
Modify decision rules to determine when to send triggers:
decision_rules = [
{"condition": "motivation >= 0.7 and ability >= 0.7", "action": "trigger"},
{"condition": "motivation < 0.7", "action": "improve_motivation"},
{"condition": "ability < 0.7", "action": "improve_ability"},
]
reasoning_engine = ReasoningEngine(llm=custom_llm, decision_rules=decision_rules)
Custom Trigger Messages
Control how the trigger message is generated:
def custom_prompt(user_context):
return f"Hey {user_context['email']}, check out this new feature!"
generator = TriggerGenerator(llm=custom_llm)
generator.generate_trigger(user_context, behavior, scores, custom_prompt)
Examples
- E-commerce Onboarding: Increase conversions by nudging users at the right time.
- SaaS Feature Adoption: Help users discover and adopt new features effectively.
- Healthcare Reminders: Encourage patients to complete follow-ups and treatments.
API Reference
See the full API documentation for detailed information on all classes and methods.
Contributing
Contributions are welcome! Please submit a Pull Request or open an issue for discussion.
Metadata
Release files for valthera 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| valthera-0.1.2.tar.gz | 13.0 kB | Without provenance | Details for valthera-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| valthera-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for valthera-0.1.2-py3-none-any.whl |
Total release size: 30.0 kB
Release files / valthera-0.1.2.tar.gz
| Download URL | valthera-0.1.2.tar.gz |
|---|---|
| Size | 13.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9f37eaebcffc508ba658479e9afdaf8c1d2982cee494604f733f8f9ff044e228
|
|
BLAKE2b-256 checksum How to use checksums |
4ca4e3d71f9ccb8a2e0c8838c5a7f8f02520237422608fa0e5e5ef787505ae9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.5 CPython/3.13.2 Darwin/24.3.0
|
Release files / valthera-0.1.2-py3-none-any.whl
| Download URL | valthera-0.1.2-py3-none-any.whl |
|---|---|
| Size | 17.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ff04b9129cd27c0e125e98d1b48223f8a3030f742ea4763c1c99a00bce063dc
|
|
BLAKE2b-256 checksum How to use checksums |
2bfa22d410d648ba31fee3486fabe959086d89a59d128fb5bde4acd155725da3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.5 CPython/3.13.2 Darwin/24.3.0
|
Security for valthera 0.1.2
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.