thoughtful-agents


Namethoughtful-agents JSON
Version 0.1.1 PyPI version JSON
download
home_pagehttps://github.com/xybruceliu/thoughtful-agents
SummaryA framework for modeling agent thoughts and conversations
upload_time2025-03-14 03:23:36
maintainerNone
docs_urlNone
authorXingyu Bruce Liu
requires_python>=3.8
licenseNone
keywords ai agents conversational ai llm proactive ai inner thoughts cognitive architecture multi-agent nlp natural language processing conversation
VCS
bugtrack_url
requirements numpy openai spacy typing-extensions
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.61282s