<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/logo_b.png" width="400">
<source media="(prefers-color-scheme: light)" srcset="docs/logo.png" width="400">
<img alt="ProactiveAgent logo." src="docs/logo.png" width="400">
</picture>
<!-- <img src="docs/logo.png" alt="ProactiveAgent Logo" width="400"/> -->
**Time-awareness for your AI Agent**
[](https://python.org)
[](https://pypi.org/project/proactiveagent/)
[](LICENSE)
*Transform your AI from reactive to proactive with intelligent timing and context-aware wake-up patterns*
[Quick Start](#quick-start) • [Documentation](https://leomariga.github.io/ProactiveAgent/) • [Examples](#examples)
</div>
## What is ProactiveAgent?
**ProactiveAgent** is an open-source Python library that packs any AI agents with intelligent **proactive behavior**. Unlike traditional agents that only respond when prompted, ProactiveAgent creates AI agents that can respond on their own. The agents are able to:
- **Decide when to speak** - Multi-factor decision engine determines *if* and *when* to respond
- **Sleep intelligently** - Dynamic timing system calculates the response intervals
- **Understand context** - Analyzes conversation flow, user engagement, and urgency
- **Stay flexible** - Fully customizable decision engines and sleep calculators
<div align="center">
<img src="docs/flow_gif.gif"/>
</div>
## Quick Start
### Installation
```bash
pip install proactiveagent
```
### Basic Usage
```python
import time
from proactiveagent import ProactiveAgent, OpenAIProvider
# Create a proactive agent: Define in natural language the frequency of response
agent = ProactiveAgent(
provider = OpenAIProvider(model="gpt-5-nano",),
system_prompt = "You are a casual bored teenager. Answer like you're texting a friend",
decision_config = {
'wake_up_pattern': "Use the pace of a normal text chat",
}
)
# Add response callback and start agent thread
def on_response(response: str):
print(f"🤖 AI: {response}")
agent.add_callback(on_response)
agent.start()
while True:
message = input("You: ").strip()
if message.lower() == 'quit': break
agent.send_message(message)
time.sleep(3)
agent.stop()
```
<div align="center">
<video src="https://github.com/user-attachments/assets/b7e724e0-9590-4f73-bb78-478bf2fa3540" width="800" loop>
</video>
</div>
## How It Works
ProactiveAgent operates on a **3-step decision cycle**:
<!-- Architecture diagram placeholder -->
<!-- <div align="center">
<img src="docs/architecture.png" alt="ProactiveAgent Architecture" width="800"/>
</div> -->
### 1. Decision Engine - "Should I Respond?"
Evaluates multiple factors to determine if the AI should respond:
- **Context Analysis**: Checks for questions, urgency keywords, and conversation flow
- **Timing**: Considers elapsed time since the last user message
- **AI Reasoning**: Uses native AI capabilities for intelligent decision-making
- **Engagement**: Monitors user activity patterns and conversation intensity
> We have other engines you can choose from and you can also define your own engine using our abstract base class. See the [Decision Engines](#decision-engines) section for details and examples.
### 2. Message Generation - "Respond"
Generates appropriate responses considering conversation history and timing.
### 3. Sleep Calculator - "How Long Should I Wait?"
Determines the best wait time before the next decision cycle. Available options:
- **AI-Based** (default): Interprets natural language patterns like *"Respond like a normal chat"*
- **Pattern-Based**: Keyword matching for different conversation states
- **Function-Based**: Custom timing functions
- **Static**: Fixed intervals
> You can also create your own SleepCalculator. See the [Sleep Calculators](#sleep-calculators) section for details and examples.
<!-- Flow diagram placeholder -->
<!-- <div align="center">
<img src="docs/decision-flow.png" alt="Decision Flow" width="600"/>
</div> -->
## Customization & Flexibility
### Decision Engines
Choose or create your own decision-making logic:
```python
from proactiveagent import DecisionEngine
# Your custom logic
class MyDecisionEngine(DecisionEngine):
async def should_respond(self, messages, last_time, context, config, triggered_by_user):
# Your custom decision logic here
return should_respond, "reasoning"
agent = ProactiveAgent(provider=provider, decision_engine=MyDecisionEngine())
```
### Sleep Time Calculators
Control when your agent "wakes up" to make decisions:
```python
from proactiveagent import AIBasedSleepCalculator, StaticSleepCalculator
# Option 1 - AI interprets natural language patterns (default)
ai_calc = AIBasedSleepCalculator(provider)
# Option 2 - Fixed intervals
static_calc = StaticSleepCalculator(sleep_time=120) # Every 2 minutes
# Option 3 - Your own custom adaptive logic
class SmartCalculator(SleepTimeCalculator):
async def calculate_sleep_time(self, config, context):
engagement = context.get('user_engagement', 'medium')
if engagement == 'high':
return 30, "High engagement - checking frequently"
elif engagement == 'low':
return 300, "Low engagement - checking less often"
return 120, "Medium engagement - standard interval"
agent.scheduler.set_sleep_time_calculator(SmartCalculator())
```
### Real-Time Monitoring
Track your agent's behavior with callbacks:
```python
def on_response(response: str):
print(f"Response: {response}")
def on_decision(should_respond: bool, reasoning: str):
status = "RESPOND" if should_respond else "WAIT"
print(f"Decision: {status} - {reasoning}")
def on_sleep_time(sleep_time: int, reasoning: str):
print(f"Sleeping {sleep_time}s - {reasoning}")
# Register callbacks
agent.add_callback(on_response)
agent.add_decision_callback(on_decision)
agent.add_sleep_time_callback(on_sleep_time)
```
## Configuration Options
Fine-tune your agent's behavior with comprehensive configuration:
```python
agent = ProactiveAgent(
provider=provider,
decision_config={
# Response timing bounds
'min_response_interval': 30, # Minimum seconds between responses
'max_response_interval': 600, # Maximum seconds before forced response
'probability_weight': 0.3, # AI decision weight
# Sleep calculation
'wake_up_pattern': "Check around 2-3 minutes when user is active",
'min_sleep_time': 30, # Minimum sleep seconds
'max_sleep_time': 600, # Maximum sleep seconds
}
)
```
<!-- You can also add your own config parameters for you customized engines and calculator. See example TODO link -->
## Examples
Explore our examples in the [`examples/`](examples/) directory:
### Getting Started
- **[`minimal_chat.py`](examples/minimal_chat.py)** - Ultra-simple chat
- **[`minimal_callbacks.py`](examples/callbacks/minimal_callbacks.py)** - Minimal chat with thought process
### Decision Engines
- **[`ai_based_decision_engine.py`](examples/decision_engines/ai_based_decision_engine.py)** - AI-powered decisions
- **[`simple_decision_engine.py`](examples/decision_engines/simple_decision_engine.py)** - Time-based logic
- **[`custom_decision_engine.py`](examples/decision_engines/custom_decision_engine.py)** - Build your own
### Sleep Calculators
- **[`ai_based_sleep_calculator.py`](examples/sleep_calculators/ai_based_sleep_calculator.py)** - Natural language patterns
- **[`function_based_sleep_calculator.py`](examples/sleep_calculators/function_based_sleep_calculator.py)** - Adaptive timing
- **[`pattern_based_sleep_calculator.py`](examples/sleep_calculators/pattern_based_sleep_calculator.py)** - Keyword matching
### Monitoring & Callbacks
- **[`minimal_callbacks.py`](examples/callbacks/minimal_callbacks.py)** - Full callback system
### Configuration
- **[`all_config_parameters.py`](examples/configs/all_config_parameters.py)** - Complete configuration guide
## Advanced Features
### Context Management
```python
# Set conversation context
agent.set_context('user_mood', 'excited')
agent.set_context('topic_urgency', 'high')
# Context automatically influences decisions
mood = agent.get_context('user_mood')
```
### Runtime Configuration
```python
# Update configuration while running
agent.update_config({
'min_response_interval': 5, # Respond faster
'engagement_threshold': 0.3 # Lower threshold
})
```
## Contributing
We welcome contributions! This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
**Quick setup:**
```bash
pip install uv
uv sync --dev # Install dependencies including dev tools
```
Please see our [Contributing Guide](CONTRIBUTING.md) for detailed instructions.
## License
This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
## Support
**Made with ❤️ by the internet**
Mainteiner: [Leonardo Mariga](https://github.com/leomariga)
Raw data
{
"_id": null,
"home_page": null,
"name": "proactiveagent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Leonardo Mariga <leomariga@gmail.com>",
"keywords": "active, agent, ai, automation, autonomous, chatbot, context-aware, conversational, decision-making, gpt, intelligent, llm, openai, proactive, scheduling, thread, timing",
"author": null,
"author_email": "Leonardo Mariga <leomariga@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1c/44/69a882b9ca51d43ed02f91ae047c7bdc74315d7582c8f81c1ec06e7caa80/proactiveagent-0.1.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/logo_b.png\" width=\"400\">\n <source media=\"(prefers-color-scheme: light)\" srcset=\"docs/logo.png\" width=\"400\">\n <img alt=\"ProactiveAgent logo.\" src=\"docs/logo.png\" width=\"400\">\n</picture>\n\n<!-- <img src=\"docs/logo.png\" alt=\"ProactiveAgent Logo\" width=\"400\"/> -->\n\n**Time-awareness for your AI Agent**\n\n[](https://python.org)\n[](https://pypi.org/project/proactiveagent/)\n[](LICENSE)\n\n*Transform your AI from reactive to proactive with intelligent timing and context-aware wake-up patterns*\n\n[Quick Start](#quick-start) \u2022 [Documentation](https://leomariga.github.io/ProactiveAgent/) \u2022 [Examples](#examples)\n\n</div>\n\n## What is ProactiveAgent?\n\n**ProactiveAgent** is an open-source Python library that packs any AI agents with intelligent **proactive behavior**. Unlike traditional agents that only respond when prompted, ProactiveAgent creates AI agents that can respond on their own. The agents are able to:\n\n- **Decide when to speak** - Multi-factor decision engine determines *if* and *when* to respond\n- **Sleep intelligently** - Dynamic timing system calculates the response intervals \n- **Understand context** - Analyzes conversation flow, user engagement, and urgency\n- **Stay flexible** - Fully customizable decision engines and sleep calculators\n\n<div align=\"center\">\n<img src=\"docs/flow_gif.gif\"/>\n</div>\n\n## Quick Start\n\n### Installation\n\n```bash\npip install proactiveagent\n```\n\n### Basic Usage\n\n```python\nimport time\nfrom proactiveagent import ProactiveAgent, OpenAIProvider\n\n# Create a proactive agent: Define in natural language the frequency of response\nagent = ProactiveAgent(\n provider = OpenAIProvider(model=\"gpt-5-nano\",),\n system_prompt = \"You are a casual bored teenager. Answer like you're texting a friend\",\n decision_config = {\n 'wake_up_pattern': \"Use the pace of a normal text chat\",\n }\n)\n\n# Add response callback and start agent thread\ndef on_response(response: str): \n print(f\"\ud83e\udd16 AI: {response}\")\n\nagent.add_callback(on_response)\nagent.start()\nwhile True:\n message = input(\"You: \").strip()\n if message.lower() == 'quit': break\n agent.send_message(message)\n time.sleep(3)\n\nagent.stop()\n```\n\n<div align=\"center\">\n<video src=\"https://github.com/user-attachments/assets/b7e724e0-9590-4f73-bb78-478bf2fa3540\" width=\"800\" loop>\n</video>\n</div>\n\n## How It Works\n\nProactiveAgent operates on a **3-step decision cycle**:\n\n<!-- Architecture diagram placeholder -->\n<!-- <div align=\"center\">\n<img src=\"docs/architecture.png\" alt=\"ProactiveAgent Architecture\" width=\"800\"/>\n</div> -->\n\n### 1. Decision Engine - \"Should I Respond?\"\n\nEvaluates multiple factors to determine if the AI should respond:\n\n- **Context Analysis**: Checks for questions, urgency keywords, and conversation flow\n- **Timing**: Considers elapsed time since the last user message\n- **AI Reasoning**: Uses native AI capabilities for intelligent decision-making\n- **Engagement**: Monitors user activity patterns and conversation intensity\n\n> We have other engines you can choose from and you can also define your own engine using our abstract base class. See the [Decision Engines](#decision-engines) section for details and examples. \n\n### 2. Message Generation - \"Respond\"\n\nGenerates appropriate responses considering conversation history and timing.\n\n### 3. Sleep Calculator - \"How Long Should I Wait?\"\n\nDetermines the best wait time before the next decision cycle. Available options:\n\n- **AI-Based** (default): Interprets natural language patterns like *\"Respond like a normal chat\"*\n- **Pattern-Based**: Keyword matching for different conversation states \n- **Function-Based**: Custom timing functions\n- **Static**: Fixed intervals\n\n> You can also create your own SleepCalculator. See the [Sleep Calculators](#sleep-calculators) section for details and examples.\n\n<!-- Flow diagram placeholder -->\n<!-- <div align=\"center\">\n<img src=\"docs/decision-flow.png\" alt=\"Decision Flow\" width=\"600\"/>\n</div> -->\n\n## Customization & Flexibility\n\n### Decision Engines\n\nChoose or create your own decision-making logic:\n\n```python\nfrom proactiveagent import DecisionEngine\n\n# Your custom logic\nclass MyDecisionEngine(DecisionEngine):\n async def should_respond(self, messages, last_time, context, config, triggered_by_user):\n # Your custom decision logic here\n return should_respond, \"reasoning\"\n\nagent = ProactiveAgent(provider=provider, decision_engine=MyDecisionEngine())\n```\n\n### Sleep Time Calculators\n\nControl when your agent \"wakes up\" to make decisions:\n\n```python\nfrom proactiveagent import AIBasedSleepCalculator, StaticSleepCalculator\n\n# Option 1 - AI interprets natural language patterns (default)\nai_calc = AIBasedSleepCalculator(provider)\n\n# Option 2 - Fixed intervals\nstatic_calc = StaticSleepCalculator(sleep_time=120) # Every 2 minutes\n\n# Option 3 - Your own custom adaptive logic\nclass SmartCalculator(SleepTimeCalculator):\n async def calculate_sleep_time(self, config, context):\n engagement = context.get('user_engagement', 'medium')\n if engagement == 'high':\n return 30, \"High engagement - checking frequently\"\n elif engagement == 'low':\n return 300, \"Low engagement - checking less often\"\n return 120, \"Medium engagement - standard interval\"\n\nagent.scheduler.set_sleep_time_calculator(SmartCalculator())\n```\n\n### Real-Time Monitoring\n\nTrack your agent's behavior with callbacks:\n\n```python\ndef on_response(response: str):\n print(f\"Response: {response}\")\n\ndef on_decision(should_respond: bool, reasoning: str):\n status = \"RESPOND\" if should_respond else \"WAIT\"\n print(f\"Decision: {status} - {reasoning}\")\n\ndef on_sleep_time(sleep_time: int, reasoning: str):\n print(f\"Sleeping {sleep_time}s - {reasoning}\")\n\n# Register callbacks\nagent.add_callback(on_response)\nagent.add_decision_callback(on_decision)\nagent.add_sleep_time_callback(on_sleep_time)\n```\n\n## Configuration Options\n\nFine-tune your agent's behavior with comprehensive configuration:\n\n```python\nagent = ProactiveAgent(\n provider=provider,\n decision_config={\n # Response timing bounds\n 'min_response_interval': 30, # Minimum seconds between responses\n 'max_response_interval': 600, # Maximum seconds before forced response\n 'probability_weight': 0.3, # AI decision weight\n \n # Sleep calculation\n 'wake_up_pattern': \"Check around 2-3 minutes when user is active\",\n 'min_sleep_time': 30, # Minimum sleep seconds\n 'max_sleep_time': 600, # Maximum sleep seconds\n }\n)\n```\n<!-- You can also add your own config parameters for you customized engines and calculator. See example TODO link -->\n## Examples\n\nExplore our examples in the [`examples/`](examples/) directory:\n\n### Getting Started\n- **[`minimal_chat.py`](examples/minimal_chat.py)** - Ultra-simple chat\n- **[`minimal_callbacks.py`](examples/callbacks/minimal_callbacks.py)** - Minimal chat with thought process\n\n### Decision Engines\n- **[`ai_based_decision_engine.py`](examples/decision_engines/ai_based_decision_engine.py)** - AI-powered decisions\n- **[`simple_decision_engine.py`](examples/decision_engines/simple_decision_engine.py)** - Time-based logic\n- **[`custom_decision_engine.py`](examples/decision_engines/custom_decision_engine.py)** - Build your own\n\n### Sleep Calculators\n- **[`ai_based_sleep_calculator.py`](examples/sleep_calculators/ai_based_sleep_calculator.py)** - Natural language patterns\n- **[`function_based_sleep_calculator.py`](examples/sleep_calculators/function_based_sleep_calculator.py)** - Adaptive timing\n- **[`pattern_based_sleep_calculator.py`](examples/sleep_calculators/pattern_based_sleep_calculator.py)** - Keyword matching\n\n### Monitoring & Callbacks\n- **[`minimal_callbacks.py`](examples/callbacks/minimal_callbacks.py)** - Full callback system\n\n### Configuration\n- **[`all_config_parameters.py`](examples/configs/all_config_parameters.py)** - Complete configuration guide\n## Advanced Features\n\n### Context Management\n```python\n# Set conversation context\nagent.set_context('user_mood', 'excited')\nagent.set_context('topic_urgency', 'high')\n\n# Context automatically influences decisions\nmood = agent.get_context('user_mood')\n```\n\n### Runtime Configuration\n```python\n# Update configuration while running\nagent.update_config({\n 'min_response_interval': 5, # Respond faster\n 'engagement_threshold': 0.3 # Lower threshold\n})\n```\n\n## Contributing\n\nWe welcome contributions! This project uses [uv](https://docs.astral.sh/uv/) for dependency management.\n\n**Quick setup:**\n```bash\npip install uv\nuv sync --dev # Install dependencies including dev tools\n```\n\nPlease see our [Contributing Guide](CONTRIBUTING.md) for detailed instructions.\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n**Made with \u2764\ufe0f by the internet**\n\nMainteiner: [Leonardo Mariga](https://github.com/leomariga) \n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A Python framework to transform your AI from reactive to proactive with intelligent timing and context-aware wake-up patterns - Your agent decides when to speak!",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://leomariga.github.io/ProactiveAgent/",
"Homepage": "https://github.com/leomariga/ProactiveAgent",
"Issues": "https://github.com/leomariga/ProactiveAgent/issues",
"Repository": "https://github.com/leomariga/ProactiveAgent"
},
"split_keywords": [
"active",
" agent",
" ai",
" automation",
" autonomous",
" chatbot",
" context-aware",
" conversational",
" decision-making",
" gpt",
" intelligent",
" llm",
" openai",
" proactive",
" scheduling",
" thread",
" timing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d4610b4df4aa3533b82689301f919980cfaf1c2a4a7f380f9e1b2ee26f30faea",
"md5": "85b3eb4c8d7a777e2d9194536c596750",
"sha256": "8bf3f75f261776262cd9b1ae6726bb9dc860792c45834caedb26b371351490f8"
},
"downloads": -1,
"filename": "proactiveagent-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85b3eb4c8d7a777e2d9194536c596750",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 31598,
"upload_time": "2025-10-16T01:36:30",
"upload_time_iso_8601": "2025-10-16T01:36:30.603723Z",
"url": "https://files.pythonhosted.org/packages/d4/61/0b4df4aa3533b82689301f919980cfaf1c2a4a7f380f9e1b2ee26f30faea/proactiveagent-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1c4469a882b9ca51d43ed02f91ae047c7bdc74315d7582c8f81c1ec06e7caa80",
"md5": "8649273ea81900861ff3c5c99d3ec44c",
"sha256": "1794e264d004f2121e0402485462a053cd110c6c3a33b4e1d6c75934fdd5df1f"
},
"downloads": -1,
"filename": "proactiveagent-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8649273ea81900861ff3c5c99d3ec44c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 1514997,
"upload_time": "2025-10-16T01:36:32",
"upload_time_iso_8601": "2025-10-16T01:36:32.853521Z",
"url": "https://files.pythonhosted.org/packages/1c/44/69a882b9ca51d43ed02f91ae047c7bdc74315d7582c8f81c1ec06e7caa80/proactiveagent-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-16 01:36:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "leomariga",
"github_project": "ProactiveAgent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "proactiveagent"
}
JSON
