{"id":3832,"library":"tom-swe","title":"Theory of Mind modeling for Software Engineering assistants","description":"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.","status":"active","version":"1.0.3","language":"en","source_language":"en","source_url":"https://github.com/All-Hands-AI/ToM-SWE","tags":["AI","Software Engineering","Theory of Mind","LLM","NLP","Agent"],"install":[{"cmd":"pip install tom-swe","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for LLM interactions; ToM-SWE builds on top of its capabilities.","package":"openai","optional":false},{"reason":"Used for data validation and settings management.","package":"pydantic","optional":false}],"imports":[{"symbol":"ToMController","correct":"from tom_swe import ToMController"},{"symbol":"System","correct":"from tom_swe import System"},{"symbol":"User","correct":"from tom_swe import User"},{"symbol":"Assistant","correct":"from tom_swe import Assistant"},{"symbol":"Reflection","correct":"from tom_swe import Reflection"}],"quickstart":{"code":"import os\nfrom tom_swe import ToMController, System, User, Assistant, Reflection\n\n# Ensure OPENAI_API_KEY is set in your environment\n# Alternatively, pass it directly: ToMController(openai_api_key=\"sk-...\")\ncontroller = ToMController(\n    openai_api_key=os.environ.get('OPENAI_API_KEY', '')\n)\n\n# Initialize with a system message\ncontroller.add_message(System(\"You are a helpful software engineering assistant.\"))\n\n# User query\ncontroller.add_message(User(\"Help me write a Python function to calculate factorial.\"))\nresponse_1 = controller.run()\nprint(f\"Assistant (initial): {response_1}\")\n\n# Add a reflection to guide the assistant's 'mind'\ncontroller.add_message(Reflection(\"The user might be looking for both iterative and recursive solutions, or error handling.\"))\n\n# Follow-up user query based on reflection\ncontroller.add_message(User(\"Can you also add some error handling for non-integer inputs?\"))\nresponse_2 = controller.run()\nprint(f\"Assistant (with reflection): {response_2}\")","lang":"python","description":"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."},"warnings":[{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"Future releases (post 1.0.x)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}