{"_id":"@blueprintlabio/theory-of-mind-ai","name":"@blueprintlabio/theory-of-mind-ai","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@blueprintlabio/theory-of-mind-ai","version":"0.1.0","type":"module","description":"A TypeScript library for building AI agents with dynamic theory of mind capabilities, featuring real-time understanding of human mental states during conversations.","author":{"name":"Blueprint Design Lab"},"license":"MIT","homepage":"https://github.com/BlueprintDesignLab/theory-of-mind-ai#readme","repository":{"type":"git","url":"git+https://github.com/BlueprintDesignLab/theory-of-mind-ai.git"},"bugs":{"url":"https://github.com/BlueprintDesignLab/theory-of-mind-ai/issues"},"keywords":["theory-of-mind","ai","psychology","mental-states","openai","gpt","conversational-ai","typescript","streaming"],"main":"./dist/core.js","types":"./dist/core.d.ts","exports":{".":{"types":"./dist/core.d.ts","import":"./dist/core.js"}},"scripts":{"dev":"vite dev","build":"vite build && npm run build:lib","build:lib":"tsc -p tsconfig.lib.json","preview":"vite preview","prepare":"svelte-kit sync || echo ''","check":"svelte-kit sync && svelte-check --tsconfig ./tsconfig.json","check:watch":"svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch","format":"prettier --write .","lint":"prettier --check . && eslint .","prepublishOnly":"npm run build:lib"},"peerDependencies":{"openai":">=5.0.0"},"devDependencies":{"@eslint/compat":"^1.2.5","@eslint/js":"^9.18.0","@sveltejs/adapter-auto":"^6.0.0","@sveltejs/kit":"^2.22.0","@sveltejs/vite-plugin-svelte":"^6.0.0","@tailwindcss/typography":"^0.5.15","@tailwindcss/vite":"^4.0.0","eslint":"^9.18.0","eslint-config-prettier":"^10.0.1","eslint-plugin-svelte":"^3.0.0","globals":"^16.0.0","prettier":"^3.4.2","prettier-plugin-svelte":"^3.3.3","prettier-plugin-tailwindcss":"^0.6.11","svelte":"^5.0.0","svelte-check":"^4.0.0","tailwindcss":"^4.0.0","typescript":"^5.0.0","typescript-eslint":"^8.20.0","vite":"^7.0.4"},"dependencies":{"openai":"^5.16.0"},"publishConfig":{"access":"public"},"_id":"@blueprintlabio/theory-of-mind-ai@0.1.0","gitHead":"f56f2f8659b4fa1dd0f435066450a9a7f49121ee","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-88JH/bhIhPfbeKxQSmp+uU/MVZrv4kO8OMYfqDmIO6NmiRj7JxEPFVs7zQ9GaqRnO17Eo4l4eiLJI6jFdPSJbw==","shasum":"ca4d4b3db22410e9893e973687ff64d5b7597689","tarball":"https://registry.npmjs.org/@blueprintlabio/theory-of-mind-ai/-/theory-of-mind-ai-0.1.0.tgz","fileCount":31,"unpackedSize":116975,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCBbfY67s7fS9YugDJtf6Hm252IZ+EaXrp2BPXbchTGIgIhAN3KRFqj2bJiFUBTt4TbBMD5nMzgiK1aLHfaLoODFq2P"}]},"_npmUser":{"name":"yail259","email":"yaillives@gmail.com"},"directories":{},"maintainers":[{"name":"yail259","email":"yaillives@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/theory-of-mind-ai_0.1.0_1756437994505_0.4675736460844764"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-29T03:26:34.056Z","0.1.0":"2025-08-29T03:26:34.697Z","modified":"2025-08-29T03:26:35.104Z"},"maintainers":[{"name":"yail259","email":"yaillives@gmail.com"}],"description":"A TypeScript library for building AI agents with dynamic theory of mind capabilities, featuring real-time understanding of human mental states during conversations.","homepage":"https://github.com/BlueprintDesignLab/theory-of-mind-ai#readme","keywords":["theory-of-mind","ai","psychology","mental-states","openai","gpt","conversational-ai","typescript","streaming"],"repository":{"type":"git","url":"git+https://github.com/BlueprintDesignLab/theory-of-mind-ai.git"},"author":{"name":"Blueprint Design Lab"},"bugs":{"url":"https://github.com/BlueprintDesignLab/theory-of-mind-ai/issues"},"license":"MIT","readme":"# Theory of Mind AI Library\n\nA TypeScript library for building AI agents with dynamic theory of mind capabilities, featuring real-time understanding of human mental states during conversations.\n\n## Overview\n\nThis project combines:\n\n1. **Core Library** (`src/lib/`) - TypeScript library for tracking and updating theory of mind understanding\n2. **Interactive Demo** (`src/routes/`) - Real-time SvelteKit web application with Apple HIG design\n\n## Core Library Features\n\n### Multi-Level Theory of Mind Tracking\n- **1st Order**: \"The human believes X\"\n- **2nd Order**: \"The human thinks I believe Y\" \n- **3rd Order**: \"The human thinks I believe they know Z\"\n\n### State Categories (Research-Based)\n- **Epistemic States**: Knowledge, beliefs, uncertainty levels\n- **Motivational States**: Goals, desires, preferences, intentions\n- **Emotional States**: Current emotions, emotional patterns\n- **Attentional States**: Focus areas, interests, attention shifts\n- **Social Awareness**: Human's understanding of the AI-human relationship\n\n### Temporal Memory System\n- Message-level granular updates\n- Confidence scoring with temporal decay\n- Historical state tracking\n- Automatic pruning of low-confidence entries\n\n## Demo Application Features\n\n### Real-Time Chat Interface\n- GPT-5 powered conversations with streaming responses\n- Live theory of mind updates per message\n- Apple HIG compliant design system with Tailwind CSS\n\n### Visualization Components\n- **Live ToM Dashboard**: Real-time state updates with smooth animations\n- **Confidence Heat Maps**: Dynamic color coding using Apple's semantic colors\n- **Temporal Timeline**: Historical view of belief evolution\n- **Multi-Level Belief Trees**: Collapsible hierarchical mental state representation\n- **Emotional Indicators**: Visual emotional state tracking\n\n## Quick Start\n\n### Installation & Development\n\n```bash\n# Clone and install dependencies\ngit clone https://github.com/your-org/theory-of-mind-ai\ncd theory-of-mind-ai\nnpm install\n\n# Add OpenAI API key to environment\necho \"OPENAI_API_KEY=your-api-key-here\" > .env.local\n\n# Start development server\nnpm run dev\n```\n\n### Using the Core Library\n\n```typescript\nimport { ToMAgent, ToMStreamHandler } from '$lib';\n\nconst agent = new ToMAgent({\n  openaiApiKey: process.env.OPENAI_API_KEY\n});\n\n// Natural conversation with ToM analysis\nconst result = await agent.respondAndAnalyze(\"I'm feeling frustrated with this task\");\nconsole.log('AI Response:', result.response);\nconsole.log('Detected mental states:', result.tomUpdates);\n\n// Real-time streaming with UI callbacks\nconst streamHandler = new ToMStreamHandler({\n  streamResponse: (delta) => console.log('Streaming:', delta),\n  updateMentalState: (state) => console.log('Mental state:', state),\n  showToolCall: (tool) => console.log('Tool call:', tool),\n  showConfidence: (conf) => console.log('Confidence:', conf),\n  showReasoning: (reasoning) => console.log('Reasoning:', reasoning),\n  onComplete: (result) => console.log('Complete:', result)\n});\n\nawait streamHandler.consume(agent, \"I'm stuck on this problem\");\n```\n\n### Example ToM Snapshot\n\n```typescript\n{\n  timestamp: 1703123456789,\n  confidence: 0.85,\n  epistemicStates: [\n    {\n      type: 'belief',\n      content: 'User believes the current task is challenging',\n      confidence: 0.9,\n      order: 1\n    }\n  ],\n  emotionalStates: [\n    {\n      type: 'frustration',\n      intensity: 0.7,\n      confidence: 0.85,\n      triggers: ['task_difficulty']\n    }\n  ],\n  motivationalStates: [\n    {\n      type: 'goal',\n      content: 'Complete the task efficiently',\n      priority: 'high',\n      confidence: 0.8\n    }\n  ]\n}\n```\n\n## Project Structure\n\n```\ntheory-of-mind-ai/\n├── src/\n│   ├── lib/\n│   │   ├── agent/          # ToMAgent main class\n│   │   ├── states/         # State type definitions\n│   │   ├── memory/         # Temporal memory management\n│   │   ├── analysis/       # GPT-5 integration for ToM reasoning\n│   │   ├── types/          # TypeScript interfaces\n│   │   └── index.ts        # Library exports\n│   ├── routes/\n│   │   ├── +page.svelte    # Main demo interface\n│   │   └── +layout.svelte  # Apple HIG layout\n│   └── app.html            # SvelteKit app template\n├── static/                 # Static assets\n└── package.json           # Dependencies and scripts\n```\n\n## Technical Stack\n\n- **Framework**: SvelteKit with Svelte 5 runes\n- **Styling**: Tailwind CSS with Apple HIG design tokens  \n- **AI**: OpenAI GPT-5 with function calling and streaming\n- **Architecture**: Tool-based natural conversations with real-time ToM updates\n- **Decay System**: Message-based confidence decay (not time-based)\n- **Language**: TypeScript\n- **Build**: Vite\n\n## Research Foundation\n\nBased on current theory of mind research:\n\n- **Baron-Cohen's Theory of Mind mechanisms**\n- **Premack & Woodruff's foundational work**\n- **Recent advances in computational theory of mind**\n- **Multi-level belief attribution models**\n- **Temporal confidence modeling in social cognition**\n\n## Development Scripts\n\n```bash\nnpm run dev          # Start development server\nnpm run build        # Build for production\nnpm run preview      # Preview production build\nnpm run check        # Type checking\nnpm run lint         # Code linting\nnpm run format       # Code formatting\n```\n\n## API Reference\n\n### ToMAgent\n\n#### Methods\n\n- `updateFromMessage(message: string): Promise<ToMUpdate>`\n- `getCurrentUnderstanding(): ToMSnapshot`\n- `getTemporalHistory(): ToMSnapshot[]`\n- `streamUpdates(): AsyncIterator<ToMUpdate>`\n\n#### Configuration\n\n```typescript\nconst agent = new ToMAgent({\n  openaiApiKey: process.env.OPENAI_API_KEY,\n  model: 'gpt-5',\n  confidenceThreshold: 0.3,\n  maxHistoryLength: 100,\n  temporalDecayRate: 0.95\n});\n```\n\n## Environment Variables\n\nCreate a `.env.local` file with:\n\n```bash\nOPENAI_API_KEY=your-openai-api-key\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**Built with ❤️ for advancing AI's understanding of human cognition**\n","readmeFilename":"README.md","_rev":"1-bdc3a6920675551a0c5e650b77f50281"}