Install & Compatibility
Where this runs
tested against v1.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
272MB installed
● package 272MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ToMAgent
✓ from tom_swe import ToMAgent
✗ from tom_swe import ToMController
RAGAgent
✓ from tom_swe import RAGAgent
create_tom_agent
✓ from tom_swe import create_tom_agent
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}")
Debug
Known issues
gotchaThe `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.fixEnsure 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')`.
affects: All
gotchaEffective 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.fixConsult 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.
affects: All
breakingAs `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.fixIt 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.
affects: Future releases (post 1.0.x)
Upgrade
Version history
1.0.3latest on PyPI · released Nov 26, 2025
Audit
Dependencies
openairequiredUsed for LLM interactions; ToM-SWE builds on top of its capabilities.
pydanticrequiredUsed for data validation and settings management.