# Thoughtful Agents
A framework for modeling agent thoughts and conversations, enabling more natural and human-like interactions between multiple AI agents and humans.
## Overview
Thoughtful Agents provides a structured approach to modeling the internal thought processes of AI agents during conversations. Rather than simply predicting conversational turns, this framework enables proactive AI driven by its own internal "thoughts".
This framework is based on the paper [Proactive Conversational Agents with Inner Thoughts](https://arxiv.org/pdf/2501.00383), published at [CHI 2025](https://doi.org/10.1145/3706598.3713760).
## Key Features
- Thinking engine for thought generation, evaluation, selection, and articulation
- System 1 (fast, automatic) and System 2 (slow, deliberate) thinking
- Mental object management (thoughts, memories)
- Saliency-based memory and thought retrieval
- Conversation and event tracking
- Turn-taking prediction and engine for determining when and who should speak next
- Proactivity configuration for agents
## Installation
```bash
pip install thoughtful-agents
```
Download the required spaCy model:
```bash
python -m spacy download en_core_web_sm
```
## Quick Start
```python
import asyncio
from thoughtful_agents.models import Agent, Conversation
from thoughtful_agents.utils.turn_taking_engine import decide_next_speaker_and_utterance, predict_turn_taking_type
async def main():
# Create a conversation with a simple context
conversation = Conversation(context="A friendly chat between Alice and Bob.")
# Create agents with specific proactivity configurations
alice = Agent(name="Alice", proactivity_config={
'im_threshold': 3.2,
'system1_prob': 0.3,
'interrupt_threshold': 4.5
})
bob = Agent(name="Bob", proactivity_config={
'im_threshold': 3.2,
'system1_prob': 0.3,
'interrupt_threshold': 4.5
})
# Add background knowledge to the agents
alice.initialize_memory("I am a software engineer who likes to code.")
bob.initialize_memory("I am a cognitive scientist who works on understanding the human mind.")
# Add agents to the conversation
conversation.add_participant(alice)
conversation.add_participant(bob)
# Alice starts the conversation
new_event = await alice.send_message("I'm recently thinking about adopting a cat. What do you think about this?", conversation)
# Predict the next speaker before broadcasting the event
turn_allocation_type = await predict_turn_taking_type(conversation)
# Broadcast the event to let all agents think
await conversation.broadcast_event(new_event)
# Decide the next speaker and their utterance
next_speaker, utterance = await decide_next_speaker_and_utterance(conversation)
if next_speaker:
await next_speaker.send_message(utterance, conversation)
print(f"{next_speaker.name}: {utterance}")
if __name__ == "__main__":
asyncio.run(main())
```
## Documentation
For more detailed documentation and examples, visit the [GitHub repository](https://github.com/xybruceliu/thoughtful-agents).
## License
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
## Citation
If you use this framework in your research, please cite:
```
@inproceedings{liu2025inner,
title={Proactive Conversational Agents with Inner Thoughts},
author={Liu, Xingyu Bruce and Fang, Shitao and Shi, Weiyan and Wu, Chien-Sheng and Igarashi, Takeo and Chen, Xiang Anthony},
booktitle = {Proceedings of the 2025 CHI Conference on Human Factors in Computing Systems},
year = {2025},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
location = {Yokohama, Japan},
series = {CHI '25},
keywords = {Full},
url = {https://doi.org/10.1145/3706598.3713760},
doi = {10.1145/3706598.3713760},
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/xybruceliu/thoughtful-agents",
"name": "thoughtful-agents",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai agents, conversational ai, llm, proactive ai, inner thoughts, cognitive architecture, multi-agent, nlp, natural language processing, conversation",
"author": "Xingyu Bruce Liu",
"author_email": "xingyuliu@ucla.edu",
"download_url": "https://files.pythonhosted.org/packages/76/df/89c38b14120e01d647c19c5dd50fcd9bb64d320d3d8610955bb1606b4ac1/thoughtful_agents-0.1.1.tar.gz",
"platform": null,
"description": "# Thoughtful Agents\n\nA framework for modeling agent thoughts and conversations, enabling more natural and human-like interactions between multiple AI agents and humans.\n\n## Overview\n\nThoughtful Agents provides a structured approach to modeling the internal thought processes of AI agents during conversations. Rather than simply predicting conversational turns, this framework enables proactive AI driven by its own internal \"thoughts\".\n\nThis framework is based on the paper [Proactive Conversational Agents with Inner Thoughts](https://arxiv.org/pdf/2501.00383), published at [CHI 2025](https://doi.org/10.1145/3706598.3713760).\n\n## Key Features\n\n- Thinking engine for thought generation, evaluation, selection, and articulation\n- System 1 (fast, automatic) and System 2 (slow, deliberate) thinking\n- Mental object management (thoughts, memories)\n- Saliency-based memory and thought retrieval\n- Conversation and event tracking\n- Turn-taking prediction and engine for determining when and who should speak next\n- Proactivity configuration for agents\n\n## Installation\n\n```bash\npip install thoughtful-agents\n```\n\nDownload the required spaCy model:\n\n```bash\npython -m spacy download en_core_web_sm\n```\n\n## Quick Start\n\n```python\nimport asyncio\nfrom thoughtful_agents.models import Agent, Conversation\nfrom thoughtful_agents.utils.turn_taking_engine import decide_next_speaker_and_utterance, predict_turn_taking_type\n\nasync def main():\n # Create a conversation with a simple context\n conversation = Conversation(context=\"A friendly chat between Alice and Bob.\")\n \n # Create agents with specific proactivity configurations\n alice = Agent(name=\"Alice\", proactivity_config={\n 'im_threshold': 3.2, \n 'system1_prob': 0.3,\n 'interrupt_threshold': 4.5\n })\n \n bob = Agent(name=\"Bob\", proactivity_config={\n 'im_threshold': 3.2,\n 'system1_prob': 0.3,\n 'interrupt_threshold': 4.5\n })\n \n # Add background knowledge to the agents\n alice.initialize_memory(\"I am a software engineer who likes to code.\")\n bob.initialize_memory(\"I am a cognitive scientist who works on understanding the human mind.\")\n \n # Add agents to the conversation\n conversation.add_participant(alice)\n conversation.add_participant(bob)\n \n # Alice starts the conversation\n new_event = await alice.send_message(\"I'm recently thinking about adopting a cat. What do you think about this?\", conversation)\n \n # Predict the next speaker before broadcasting the event\n turn_allocation_type = await predict_turn_taking_type(conversation)\n \n # Broadcast the event to let all agents think\n await conversation.broadcast_event(new_event)\n \n # Decide the next speaker and their utterance\n next_speaker, utterance = await decide_next_speaker_and_utterance(conversation)\n \n if next_speaker:\n await next_speaker.send_message(utterance, conversation)\n print(f\"{next_speaker.name}: {utterance}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Documentation\n\nFor more detailed documentation and examples, visit the [GitHub repository](https://github.com/xybruceliu/thoughtful-agents).\n\n## License\n\nThis project is licensed under the Apache 2.0 License - see the LICENSE file for details.\n\n## Citation\n\nIf you use this framework in your research, please cite:\n\n```\n@inproceedings{liu2025inner,\n title={Proactive Conversational Agents with Inner Thoughts},\n author={Liu, Xingyu Bruce and Fang, Shitao and Shi, Weiyan and Wu, Chien-Sheng and Igarashi, Takeo and Chen, Xiang Anthony},\n booktitle = {Proceedings of the 2025 CHI Conference on Human Factors in Computing Systems},\n year = {2025},\n publisher = {Association for Computing Machinery},\n address = {New York, NY, USA},\n location = {Yokohama, Japan},\n series = {CHI '25},\n keywords = {Full}, \n url = {https://doi.org/10.1145/3706598.3713760},\n doi = {10.1145/3706598.3713760},\n}\n``` \n",
"bugtrack_url": null,
"license": null,
"summary": "A framework for modeling agent thoughts and conversations",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/xybruceliu/thoughtful-agents/issues",
"Documentation": "https://github.com/xybruceliu/thoughtful-agents",
"Homepage": "https://github.com/xybruceliu/thoughtful-agents",
"Source Code": "https://github.com/xybruceliu/thoughtful-agents"
},
"split_keywords": [
"ai agents",
" conversational ai",
" llm",
" proactive ai",
" inner thoughts",
" cognitive architecture",
" multi-agent",
" nlp",
" natural language processing",
" conversation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d6676b60e40264fe6c8ade4e11f2289934b96d5c52450dc846052734b73ba74d",
"md5": "4d761be2aa22e40530f0959bd9054a9a",
"sha256": "4d55bc30546106afb3923e4215adb8a490260c80d94015127c5e59b7b68bad46"
},
"downloads": -1,
"filename": "thoughtful_agents-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d761be2aa22e40530f0959bd9054a9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32435,
"upload_time": "2025-03-14T03:23:33",
"upload_time_iso_8601": "2025-03-14T03:23:33.330751Z",
"url": "https://files.pythonhosted.org/packages/d6/67/6b60e40264fe6c8ade4e11f2289934b96d5c52450dc846052734b73ba74d/thoughtful_agents-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "76df89c38b14120e01d647c19c5dd50fcd9bb64d320d3d8610955bb1606b4ac1",
"md5": "e66aa41cccee07d3b34704e65d226268",
"sha256": "d45e8cd2c7b429317e5fd730a5df0e6158737fd391e4399c54fc953e014e8c13"
},
"downloads": -1,
"filename": "thoughtful_agents-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e66aa41cccee07d3b34704e65d226268",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 667964,
"upload_time": "2025-03-14T03:23:36",
"upload_time_iso_8601": "2025-03-14T03:23:36.092846Z",
"url": "https://files.pythonhosted.org/packages/76/df/89c38b14120e01d647c19c5dd50fcd9bb64d320d3d8610955bb1606b4ac1/thoughtful_agents-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-14 03:23:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xybruceliu",
"github_project": "thoughtful-agents",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.20.0"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "spacy",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "thoughtful-agents"
}
JSON
