Theory of Mind modeling for Software Engineering assistants

1.0.3 · active · verified Sat Apr 11

ToM-SWE (Theory of Mind - Software Engineering) is a Python library designed to imbue LLM-based software engineering assistants with a 'Theory of Mind' (ToM). This allows assistants to better understand and anticipate user intentions, beliefs, and goals, leading to more contextually relevant and helpful interactions. The current version is 1.0.3, with minor updates released periodically for optimizations and typing.

Warnings

gotcha The `ToMController` fundamentally relies on a valid OpenAI API key. An incorrect, missing, or expired `OPENAI_API_KEY` will result in `AuthenticationError` or similar issues originating from the underlying `openai` library calls, rather than an error within `tom-swe` itself.
Fix: Ensure the `OPENAI_API_KEY` environment variable is correctly configured and that your key is active. Alternatively, pass the API key directly when initializing the controller: `ToMController(openai_api_key='your_key')`.
gotcha Effective utilization of `Reflection` and other ToM components requires a clear understanding of how they modify the LLM's internal state and subsequent responses. Misapplying or poorly crafting reflections can lead to suboptimal or unexpected model behavior, potentially degrading the 'Theory of Mind' benefits.
Fix: Consult the `tom-swe` documentation and examples to grasp the intended use cases for reflections. Experiment with different reflection strategies and observe their impact on the assistant's responses to fine-tune your interaction patterns.
breaking As `tom-swe` is an actively developed library (currently in early major versions), minor releases might introduce breaking changes to the API surface or core behavioral logic. While efforts are made for stability, users should anticipate and verify behavior upon upgrades.
Fix: It is recommended to pin `tom-swe` to a specific version (e.g., `tom-swe==1.0.3`) in your `requirements.txt`. Carefully review release notes for any significant updates before upgrading to a new version and thoroughly test your integrations.

Install

pip install tom-swe Install stable version

Imports

ToMController
```
from tom_swe import ToMController
```
System
```
from tom_swe import System
```
User
```
from tom_swe import User
```
Assistant
```
from tom_swe import Assistant
```
Reflection
```
from tom_swe import Reflection
```

Quickstart

This quickstart demonstrates how to initialize the `ToMController`, add system and user messages, and crucially, use `Reflection` to inject Theory of Mind insights. The controller then processes these messages and reflections to generate more informed responses from the underlying LLM.

import os
from tom_swe import ToMController, System, User, Assistant, Reflection

# Ensure OPENAI_API_KEY is set in your environment
# Alternatively, pass it directly: ToMController(openai_api_key="sk-...")
controller = ToMController(
    openai_api_key=os.environ.get('OPENAI_API_KEY', '')
)

# Initialize with a system message
controller.add_message(System("You are a helpful software engineering assistant."))

# User query
controller.add_message(User("Help me write a Python function to calculate factorial."))
response_1 = controller.run()
print(f"Assistant (initial): {response_1}")

# Add a reflection to guide the assistant's 'mind'
controller.add_message(Reflection("The user might be looking for both iterative and recursive solutions, or error handling."))

# Follow-up user query based on reflection
controller.add_message(User("Can you also add some error handling for non-integer inputs?"))
response_2 = controller.run()
print(f"Assistant (with reflection): {response_2}")

view raw JSON →